In-app calling

A call with your agent can work like a WhatsApp call. The customer taps Call in your app — or your agent rings them, on the lock screen, with the system's own incoming-call screen — and the conversation carries on with the screen off, over Bluetooth, while they open other apps.

The iOS and Android SDKs do this with a native call engine: the call's audio runs in your app's own process with the platform's echo canceller, so it rings through CallKit and VoIP pushes on iOS and a full-screen call notification on Android. React Native and Flutter apps use the same engine, through @graineai/inapp-react-native-calls and graine_inapp. You add a few lines to your app, and your server sends one push when it wants the agent to call someone.

How it works

The customer calls the agent

1. The customer taps your call button; your app calls startCall(reason:).
2. The SDK places the call — the system's call screen on iOS, the SDK's call screen on Android — and connects to the agent. The agent hears who_called = "customer" and the reason.
3. When it ends, the SDK reports the outcome to your app.

The agent calls the customer

1. Your server decides to call (a payment is due, a delivery slipped, a callback the customer booked) and sends a push to the customer's devices — or, with hosted ringing, Graine rings them for a call the agent, the customer or your team booked.
2. The SDK rings — CallKit on iOS, a call notification on Android — even when the app is closed or the phone is locked.
3. The customer answers; the SDK connects to the agent with who_called = "agent", the reason and any variables from the push.
4. The SDK reports every outcome to your app — answered, declined, missed, ended or failed — and your app tells your server.

There are two ways to ring. Your own push server: Graine holds no push tokens and rings nothing — your server knows your customers, their devices and when they agreed to be called, and it sends the push and keeps the record. Hosted ringing: you upload your APNs key and Firebase service account once, the SDK registers each device with Graine, and Graine rings it when a booked call is due and records every outcome. Tokens and credentials are stored encrypted; a dead token is deleted, and a device unseen for 90 days with it. Hosted ringing

This page sets calls up, platform by platform.

Before you start

The prompt. The SDK sets who_called on every call, and call_reason whenever the call has a reason. A variable nothing sets is left out of the prompt, so write it for both directions, and for a call with no reason:

If {who_called} is "agent", you are calling the customer: greet them by name,
say you are calling from Acme, and ask whether now is a good time. The reason
for the call, if there is one: {call_reason}. If {who_called} is "customer",
they called you: ask how you can help.

iOS

<key>NSMicrophoneUsageDescription</key>
<string>Used to talk to the assistant.</string>

import SwiftUI
import GraineInApp
 
@main
struct AcmeApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) private var appDelegate
    var body: some Scene { WindowGroup { ContentView() } }
}
 
final class AppDelegate: NSObject, UIApplicationDelegate, GraineCallsListener {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        let graine = GraineInApp.configure(GraineConfig(
            baseUrl: "https://www.graine.ai",
            publishableKey: "pk_live_…"                   // Agent → Embed & Widgets
        ))
        graine.calls.configure(GraineCallsConfig(displayName: "Acme Assistant"))
        graine.calls.addListener(self)                     // held weakly; the app delegate lives for the app's life
        graine.calls.enableVoIPPushes { token in           // hex; nil when iOS invalidates it
            guard let token = token else { return }
            Backend.saveDevice(platform: "ios", token: token)
        }
        return true
    }
 
    // What became of each call — tell your server.
    func onCallOutcome(_ outcome: GraineCallOutcome, callId: String) {
        Backend.reportOutcome(callId: callId, outcome: outcome.wire, endReason: outcome.endReason?.rawValue)
    }
}

struct ContentView: View {
    @ObservedObject private var calls = GraineInApp.shared.calls
 
    var body: some View {
        Button("Call the assistant") {
            calls.startCall(reason: "support")             // the call's id; nil while another call is live
        }
        .fullScreenCover(isPresented: .constant(calls.state != .idle)) {   // up until idle, to show how it ended
            GraineCallView()                               // or your own screen, drawn from `calls`
        }
    }
}

For a screen of your own, GraineCalls is an ObservableObject: state (idle, ringing, connecting, active, ended), callId, callerName, muted, speakerOn, agentSpeaking, caption and connectedAt, with answer(), end(), setMuted(_:) and setSpeaker(_:) (the earpiece by default, like a phone call). The full list is in the iOS reference.

Calls over WebRTC (optional)

Add the GraineInAppRTC package — Xcode → File → Add Package Dependencies → https://github.com/GraineAI/inapp-ios-rtc, the same version as GraineInApp, its GraineInAppRTC library in your app's target (CocoaPods: pod 'GraineInAppRTC', :git => 'https://github.com/GraineAI/inapp-ios-rtc.git', :tag => '0.10.3') — and calls in both directions carry their audio over WebRTC. No code, no capability: the calls find it by themselves. One Info.plist entry, for the App Store: 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. About 12 MB more installed. The choice, the dashboard switch and the fallback: WebRTC or the WebSocket.

Android

// app/build.gradle.kts
dependencies {
    implementation("ai.graine:inapp-android:0.7.0")
    implementation(platform("com.google.firebase:firebase-bom:<latest>"))
    implementation("com.google.firebase:firebase-messaging")
}

class AcmeApp : Application() {
    override fun onCreate() {
        super.onCreate()
        val graine = GraineInApp.init(this, GraineConfig(
            baseUrl = "https://www.graine.ai",
            publishableKey = "pk_live_…",                  // Agent → Embed & Widgets
        ))
        graine.calls.configure(GraineCallsConfig(
            displayName = "Acme Assistant",
            smallIcon = R.drawable.ic_stat_call,           // monochrome; 0 → the platform's call icon
        ))
        graine.calls.addListener(object : GraineCallListener {
            override fun onCallOutcome(callId: String, outcome: GraineCallOutcome) {
                // answered · declined · missed · ended · failed — tell your server, off the main thread
                Backend.reportOutcome(callId, outcome.wire, outcome.endReason?.wire)
            }
        })
    }
}

class AcmeMessagingService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        GraineCalls.onNewToken(this, token)
        Backend.saveDevice(platform = "android", token = token)
    }
 
    override fun onMessageReceived(message: RemoteMessage) {
        if (GraineCalls.handlePush(this, message.data)) return
        // …your app's other pushes
    }
}

<!-- AndroidManifest.xml, inside <application> -->
<service android:name=".AcmeMessagingService" android:exported="false">
    <intent-filter><action android:name="com.google.firebase.MESSAGING_EVENT" /></intent-filter>
</service>

fun askForCallPermissions() {
    val calls = GraineInApp.get().calls
    calls.requestCallPermissions(this) { p ->
        // GRANTED · DENIED (not yet) · BLOCKED (only Settings can change it) · NOT_NEEDED
        if (p.fullScreen == GraineCallPermissionStatus.BLOCKED) calls.openCallSettings(GraineCallPermission.FULL_SCREEN)
    }
}

callButton.setOnClickListener {
    GraineInApp.get().calls.startCall(this, reason = "support")   // the call's id; null while another call is live
}

The call screen. GraineCallActivity rings (Answer, Decline) and then shows the call (status, the line being said, mute, speaker, end), over the lock screen. The call itself runs in a foreground service, so locking the phone or opening another app does not end it; the ongoing notification has Hang up.

For your own screen, name it in GraineCallsConfig(callActivity = …) and draw it from GraineInApp.get().calls (state, call, muted, speaker, agentSpeaking, caption, connectedAt) and GraineCallListener (onCallState, onCallCaption, onAgentSpeaking, onCallControls), with answer(), decline(), end(), setMuted() and setSpeaker(). The SDK opens your activity for a ring and for Answer, which gives it three more jobs:

• Show over the lock screen — setShowWhenLocked(true) and setTurnScreenOn(true) — as the SDK's own screen does.
• Forward onRequestPermissionsResult to GraineInApp.get().calls: the SDK asks for the microphone from the call screen.
• Pass new intents on if the activity is singleTop or singleTask: call setIntent(intent) in onNewIntent, because Answer can arrive as a new intent.

The full list is in the Android reference and the calling reference.

Calls over WebRTC (optional)

Add the WebRTC module beside the SDK, at the same version, and calls in both directions carry their audio over WebRTC:

implementation("ai.graine:inapp-android-rtc:0.10.3")   // the same version as ai.graine:inapp-android

Nothing else changes in your code. The module's manifest adds ACCESS_NETWORK_STATE (a normal permission: nothing is asked) and its R8 rules ship inside it. About 7.4 MB more installed on a 64-bit phone. The choice, the dashboard switch and the fallback: WebRTC or the WebSocket.

Permissions and the setup check

What the SDK does by itself: the call itself — CallKit and VoIP pushes on iOS; on Android the ring, the call screen and the microphone service, every manifest entry merged — the call going on with the screen off, the microphone asked for when a call starts without it, and every outcome reported.

What your app adds: the iOS capabilities and Info.plist entries (an SDK cannot add them; with Expo, the React Native calls package's config plugin does), Firebase in the app on Android (the SDK's own messaging service does the rest), and one call to ask for the permissions at a moment you choose — the SDK never asks on its own at launch:

Each permission — microphone, notifications (Android), fullScreen (Android 14+) — is granted, denied (not yet), blocked (only Settings can change it) or notNeeded (iOS's notifications and full screen: CallKit).

What is still missing. At configure the SDK checks the setup — on iOS the usage string, the audio and voip background modes, the push entitlement, enableVoIPPushes and the VoIP token; on Android the manifest, the push token, notifications and the full-screen ring; on both the microphone and whether Graine can ring this phone — and logs each problem once with the exact fix. callSetupProblems returns the same list as codes and sentences. Every code: Permissions → What is still missing.

Your server

Three jobs: remember each customer's devices, ring them, and record what happened.

1. Store devices. Your app sends its token after launch (saveDevice above): an iOS VoIP token or an Android FCM token, per customer and device.

2. Ring. Create a call record (call_id, the customer, the reason, status ringing), then push to each of their devices. The push carries string values:

Send iOS pushes as VoIP pushes through APNs (apns-push-type: voip, topic <bundle id>.voip, priority 10, expiration 0) and Android pushes as high-priority, data-only FCM messages with a 30-second lifetime. The request details, the error codes, a reference implementation in Node.js and how to send a test push are in Your calling server.

3. Record what happened. Your app reports each outcome with the call_id (reportOutcome above). Mark the call missed if no answered arrives within about 45 seconds of the push — a missed report alone decides nothing, since another device or a repeated push can send one for a call that was answered; show missed calls in your app with a Call back that is startCall with the same reason; and ring again only by your own rules — once, at a sensible hour, is plenty. The conversation itself (transcript, outcome, the actions the agent took) is in Call History under the customer's name from identify().

Call states and outcomes

One call at a time: a ring that arrives during a call is reported missed without disturbing the call, and startCall returns nothing while a call is live.

Test it

1. Place a call from the app on a real device. The agent should open with the reason you sent; in Call History the conversation appears under the customer's name.
2. Ring the device from your server, three ways: with the app open, in the background, and closed (swiped away). Each must ring — the system's incoming call on iOS, the full-screen ring on a locked Android phone.
3. Answer from the lock screen, lock it again and keep talking; switch to another app mid-call.
4. Decline one and let one ring out: declined and missed reach your server with the right call_id, and nothing rings twice.
5. Ring during a live call: it is reported missed; the call is untouched.
6. Hang up from both sides; the system's call screen (iOS) and the ongoing notification (Android) go away with the call.
7. A Bluetooth headset: the call follows it, as a phone call does.

Turn on debug in GraineConfig while testing on iOS and Android: the call's main steps go to the Xcode console or logcat (tag Graine) — in React Native and Flutter, set debug: true in the calls options — and audio, messages and variable values are never logged. The full test plan, the App Store and Google Play requirements and a go-live checklist are in Test and release.

Troubleshooting

React Native and Flutter

React Native and Flutter apps get the same native call engine as the iOS and Android SDKs: the same ring, call screens, CallKit and VoIP pushes, the same push from your server and the same outcomes. Your Dart or JavaScript configures it, starts calls and answers the agent's actions.

Both are native code, so adding them needs a new store build, not an over-the-air update. On iOS, add the capabilities and Info.plist keys from iOS, step 2 — with Expo, the calls package's config plugin adds them: "plugins": ["@graineai/inapp-react-native-calls"] in app.json. On Android there is nothing to add to your manifest. Both ask for the permissions with requestCallPermissions() and say what is missing with callSetupProblems() (above).

WebRTC is a build switch in both: ENV["GRAINE_WEBRTC"] = "1" at the top of ios/Podfile (then pod install) and graineWebRtc=true in android/gradle.properties — or GRAINE_WEBRTC=1 in the build's environment on a build server. Then calls in both directions carry their audio over WebRTC (callTransport in the options chooses; transport in the call's state says which ran). Calls over WebRTC

A call screen of your own should treat ended and idle alike: on Android the state can go straight to idle from ringing, connecting or active, and the outcome says how the call ended. A call ends a conversation in the assistant bar, and the bar waits until it is over — in React Native once you attach the in-app SDK's client (0.40.2 or later), below.

Who draws the call while your app is open is callScreen. "sdk" (the default) shows the SDK's call screen: the full-screen call activity on Android, and a full-screen view over your app on iOS. "app" leaves it to your own screen, drawn from the call's state. A locked iPhone always shows the system's call screen.

React Native

npm install @graineai/inapp-react-native-calls
cd ios && pod install

Android pushes reach the engine by itself. Add Firebase to the Android app. With Expo, name your google-services.json in the app config (android.googleServicesFile) and add the package's plugin — it brings Firebase Cloud Messaging. In a bare app, add google-services.json and the Google services Gradle plugin, and graineFirebaseMessaging=true to android/gradle.properties. The package's own messaging service then rings each call push, even when the app was closed, and the engine reads the push token at launch — no JavaScript.

Already use @react-native-firebase/messaging? Its messaging service receives every message instead, so hand the engine its pushes first — in index.js, and while the app is open — and refreshed tokens:

// index.js — before AppRegistry.registerComponent
import messaging from "@react-native-firebase/messaging";
import { GraineCalls } from "@graineai/inapp-react-native-calls";
 
messaging().setBackgroundMessageHandler(async (message) => {
  if (await GraineCalls.handlePush(message.data ?? {})) return;   // a Graine call: it rings
  // …your other pushes
});
messaging().onMessage((m) => GraineCalls.handlePush(m.data ?? {}));                    // app open
messaging().onTokenRefresh((token) => GraineCalls.registerPushToken({ token }));

Configure it once, at launch. The options are kept natively, so a VoIP push that wakes a closed iPhone rings before any JavaScript has run.

import { GraineCalls } from "@graineai/inapp-react-native-calls";
 
export async function setUpCalls() {
  await GraineCalls.configure({
    publishableKey: "pk_live_…",
    displayName: "Acme Assistant",   // the ring and the call screen
  });
  GraineCalls.enableVoIPPushes((token) => myServer.saveVoipToken(token));   // iOS; null when invalidated
  GraineCalls.onOutcome((o) => myServer.reportCall(o.callId, o.outcome)); // answered · declined · missed · ended · failed
}

Give the call your screen context and actions. With the in-app SDK (@graineai/inapp-react-native 0.40.2+), attach its client once inside GraineProvider: who the customer is, your prompt variables, the current screen and your useGraineAction handlers reach the call and stay in step. A call also ends a conversation in the bar, and the bar waits until the call is over.

import { useEffect } from "react";
import { useGraineClient } from "@graineai/inapp-react-native";
import { GraineCalls } from "@graineai/inapp-react-native-calls";
 
export function CallsBridge() {
  const client = useGraineClient();
  useEffect(() => GraineCalls.attach(client), [client]);
  return null;
}

The customer calls the agent from your call button:

const id = await GraineCalls.startCall({ reason: "card_blocked" });   // null while another call is live

To offer a call from the assistant bar, ride a button on it: accessory={<GraineBarAction label="Call Asha" onPress={…} />} on GraineVoiceBar draws one in the brand's design (GraineBarAction).

With callScreen: "app", draw the call from useGraineCall() — state, callId, direction, reason, callerName, muted, speakerOn, agentSpeaking, caption, connectedAt and error — with answer(), decline(), end(), setMuted() and setSpeaker().

Flutter

dependencies:
  graine_inapp: ^0.7.0

Android pushes reach the SDK by itself. Add Firebase to the Android app: google-services.json in android/app, the Google services Gradle plugin, and Firebase Cloud Messaging in android/app/build.gradle.kts:

dependencies {
    implementation(platform("com.google.firebase:firebase-bom:<latest>"))
    implementation("com.google.firebase:firebase-messaging")
}

The SDK's own messaging service then rings each call push natively, even when the app was closed, and the SDK reads the push token at launch — no Dart.

Already use firebase_messaging? Its messaging service receives every message instead, so hand the SDK its pushes first, and refreshed tokens:

@pragma('vm:entry-point')
Future<void> onBackgroundPush(RemoteMessage message) async {
  await GraineCalls.instance.handlePush(message.data);   // rings, even when the app was closed
}
 
// in main(), after Firebase.initializeApp():
FirebaseMessaging.onBackgroundMessage(onBackgroundPush);
FirebaseMessaging.onMessage.listen((m) => GraineCalls.instance.handlePush(m.data));   // app open
FirebaseMessaging.instance.onTokenRefresh.listen(GraineCalls.instance.registerPushToken);

import 'package:graine_inapp/graine_inapp.dart';
 
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  GraineInApp.init(const GraineConfig(baseUrl: 'https://www.graine.ai', publishableKey: 'pk_live_…'));
  final calls = GraineCalls.instance;
  await calls.configure(const GraineCallsOptions(
    publishableKey: 'pk_live_…',
    displayName: 'Acme Assistant',   // the ring and the call screen
  ));
  calls.enableVoIPPushes((token) => myServer.saveVoipToken(token));   // iOS; null when invalidated
  calls.attach();                                                      // your screen context and actions
  calls.outcomes.listen((o) => myServer.reportCall(o.callId, o.wire));
  runApp(const MyApp());
}

attach() hands the call what your app already tells the agent through GraineInApp — identify, setVariables, setScreen and registerAction — and keeps it in step. The customer calls the agent with GraineCalls.instance.startCall(reason: 'card_blocked'), which returns the call's id, or null while another call is live.

With callScreen: GraineCallScreen.app, draw the call yourself: GraineCalls.instance is a ValueListenable<GraineCallSnapshot>, so a ValueListenableBuilder redraws your screen as the call moves, with answer(), decline(), end(), setMuted() and setSpeaker().

Talking with the screen off

On the native call engine, the call keeps going with the screen off by itself. An app that cannot add a native module (an Expo Go build, a release shipped only over the air) can still hold a call on the in-app engine, with two differences: the ring and the call screen are yours (a notification; not CallKit, because a web view cannot keep its microphone during a CallKit call), and the call must be told to outlive the screen — endOnBackground={false} on GraineProvider (React Native, honoured for calls from 0.40.1) or GraineConfig(endOnBackground: false) (Flutter), with a microphone foreground service on Android. On iOS, whether a web view keeps its microphone in the background has changed between iOS versions: test it on the versions you support, and keep endOnBackground on where it mutes, so the call ends cleanly.