Permissions

One rule covers every SDK: the SDK never asks on its own at launch. It asks for the microphone when a call starts without it; for calls, one call — requestCallPermissions() — asks for everything the system's dialogs can still ask for, at a moment your app chooses. What a feature needs at build time your app declares (the calls packages' Android manifests merge it for you), and the SDK's setup check says, in plain words, anything that is still missing.

At a glance

Who adds what, per SDK:

How it works

Voice in the bar

The microphone, on every platform.

• NotAllowedError is a refusal; NotFoundError is a device with no usable microphone.
• The SDK never asks twice by itself. A later call asks again only where the system allows: iOS shows its dialog once, then only Settings can change it; Android may show it again, until the customer has refused it for good.
• Nothing falls back. A refused microphone never moves the call to another transport.
• iPhone's ringer switch. React Native leaves the audio session to your app: while a call is live set playsInSilentModeIOS: true and allowsRecordingIOS: true, or the agent is silent whenever the ringer is off. The native iOS SDK sets its own session.

Calls

Native calls — the customer calls the agent, or the agent's call rings the customer — need more, because they run with the screen off and ring on the lock screen.

Asking, reading and opening Settings

Every SDK has the same four, in its own idiom:

Three permissions, each with one of four statuses:

granted; denied — not yet, asking may still change it; blocked — only Settings can change it; notNeeded — this phone needs no such permission. allGranted is true when each one is granted or not needed. Asking never leaves your app: the full-screen ring, which has no dialog, is opened with openCallSettings. Read the permissions again when your app returns to the foreground — the customer may have changed Settings.

What is still missing

At calls.configure the SDK checks the app's setup for calls and logs each problem once, as a warning with the exact fix — in Xcode's console (subsystem ai.graine.inapp) and logcat, and also in Metro's console (React Native) or the flutter run console in a development build. callSetupProblems returns the same list, each a stable code and a message:

A problem is never an exception: calls still work wherever they can.

Not using calls

On Android 14 and later, Google Play asks apps that declare USE_FULL_SCREEN_INTENT or FOREGROUND_SERVICE_MICROPHONE to explain why. An app that never places a call can remove them, and the call's service, in its own manifest — see Android → Calls. POST_NOTIFICATIONS and FOREGROUND_SERVICE can go too; an app that keeps calls must keep all of them.

Hosted ringing

No new permission. A call Graine rings needs exactly what any call that rings needs — the iOS capabilities, and on Android the notification and full-screen permissions above. What changes is who holds the tokens: on iOS, enableVoIPPushes at launch registers the VoIP token with Graine; on Android, with Firebase in the app, the SDK registers Firebase's token itself (an app with its own messaging service hands it over in onNewToken). Hosted ringing

Bluetooth and headsets

No permission on any platform. A call goes to a Bluetooth headset or car kit when one is connected, else a wired headset, else the earpiece, and follows when a headset comes or goes. On Android that routing runs on MODIFY_AUDIO_SETTINGS, which every SDK already declares — no BLUETOOTH_CONNECT. On iOS the call's audio session allows Bluetooth hands-free, with no Bluetooth usage description. Voice in the bar follows the phone's current audio route.

Asking at the right moment

Ask during onboarding, at a moment that explains itself ("Talk to Asha"), and before the first call — then the SDK never prompts in the middle of one. With calls, requestCallPermissions() is that one line on every SDK (the table above); the examples below ask without the calls API, for voice in the bar.

import { PermissionsAndroid, Platform } from "react-native";
import { requestMicrophonePermission } from "@graineai/inapp-react-native";
 
export async function askForAgentPermissions() {
  // Android shows your words; iOS resolves true and asks on first use.
  await requestMicrophonePermission({
    title: "Talk to Asha",
    message: "Allow the microphone so you can talk to the assistant.",
    buttonPositive: "Allow",
  });
  if (Platform.OS === "android" && Platform.Version >= 33) {
    await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS); // calls only
  }
}

The words to use

Store review

The App Store

• Voice over IP is for calls only. iOS requires every VoIP push to be reported to CallKit at once and stops delivering them to apps that do not. The SDK reports every one; send VoIP pushes only for calls.
• Review notes. Say the app offers voice calls with your assistant, give the reviewer a test account and where the call button is, and describe how your agent's calls ring — the reviewer cannot receive your push.
• Privacy. The microphone purpose string is required — and, with the WebRTC module, the camera one, NSCameraUsageDescription — WebRTC contains camera code, and App Store processing refuses a build that references the camera without it (ITMS-90683: the build never reaches TestFlight). Calls are audio only; say so, for example Calls are audio only. The camera is never turned on. The SDK ships a privacy manifest declaring the required-reason APIs it calls — system boot time, for timing, and UserDefaults — and no tracking. What your app collects through the agent, the customer's voice included, goes in your App Privacy details.
• China. Apple does not allow CallKit in apps on the App Store in China: leave calls off there.
• Self-contained apps (guideline 2.5.2). The SDK downloads no code. What the agent sends while it runs is content and settings — its words, its voice, the cards and choices it shows, and your Garage design — drawn by code already in your app. Apple does reject builds that carry development tools able to load code from a URL: leave them out of store builds. With Expo, remove the development client (expo-dev-client) from the build you submit — it compiles into release builds even though it only runs in development. Over-the-air JavaScript updates are your app's choice; keep them to fixes within the features Apple reviewed.
• A note for the reviewer. For example: "The app includes an AI assistant you can chat and talk with. Its replies, its voice and the appearance of the chat and call screens are delivered as content and settings from our server and drawn by the app's own code; no executable code is downloaded. Calls use CallKit and VoIP push only for real incoming calls."

Google Play

• Foreground service. Apps targeting Android 14 or later declare each foreground service type in Play Console (App content → Foreground service permissions). The call's service is type microphone: describe it as two-way voice calls with your assistant that keep going when the screen locks, and link a short video of one.
• Full-screen intent. Granted by default only to apps whose main purpose is calling or alarms; other apps declare it in Play Console, or go without — the ring is then a heads-up notification.
• Data safety. Declare the audio your app sends for the conversation.
• Executable code. Google Play forbids apps from downloading code (dex files or native libraries) outside Play. The SDK downloads none; the agent's replies, components and your design arrive as content.

Troubleshooting

Where next