ionic-callkit

v1.0.0-beta.4

Published

25 days ago

Native call UI for Ionic/Capacitor: CallKit + PushKit on iOS, ConnectionService + FCM on Android

0High
0Medium
0Low

kaoschuks

capacitor plugin native ionic callkit pushkit voip connectionservice

ionic-callkit

Native incoming / outgoing call UI for Ionic & Capacitor 7 apps.

| Platform | Native layer | Push | |---|---|---| | Android | Self-managed ConnectionService (ported from react-native-callkeep), full-screen ringing notification, phoneCall foreground service | FCM (data-only, high priority) | | iOS | CallKit (CXProvider) | PushKit VoIP | | Web | Emits the same events so you can drive an HTML call screen | — |

The plugin shows and tracks the call. Media is yours: start your WebRTC / SIP session on callAnswered / callStarted and stop it on callEnded.

Status: Android, iOS and web implement the API below. Android is verified on an emulator; the iOS implementation (ported from callkeep's RNCallKeep.m) still needs its first build and device test — see WORK.md. The previous iOS plugin_events listener is gone; the legacy ConnectionId / Username push keys are still accepted.

Install

npm install ionic-callkit
npx cap sync

Requires Capacitor 7, Android 8.0+ (API 26) and iOS 14+.

Android setup

Firebase — add your app in the Firebase console and place google-services.json in android/app/. The Capacitor Android template applies the Google Services plugin automatically when that file exists.
minSdk 26 — in android/variables.gradle set minSdkVersion = 26.
Permissions — the plugin manifest already declares everything self-managed mode needs (MANAGE_OWN_CALLS, RECORD_AUDIO, FOREGROUND_SERVICE_PHONE_CALL, FOREGROUND_SERVICE_MICROPHONE, POST_NOTIFICATIONS, USE_FULL_SCREEN_INTENT, …). At runtime call requestPermissions() for microphone + notifications.
Full-screen intent (Android 14+) — Google Play only grants USE_FULL_SCREEN_INTENT by default to calling / alarm apps. Check canUseFullScreenIntent() and send the user to openFullScreenIntentSettings() if needed; without it a locked phone shows a heads-up notification instead of the full-screen call.
Incoming-call screen — when the phone is locked or the screen is off, the ringing call opens a native full-screen call screen (caller, Answer, Decline) over the lock screen, even a PIN/biometric one; Answer then opens your app over the lock screen. When the phone is unlocked and in use, Android shows a heads-up notification with Answer/Decline instead (same as every calling app). Set android.incomingCallScreen: 'app' to open your own call page instead of the native screen. Translate / restyle the native screen by overriding the ionic_callkit_* strings and colors in your app's res/values.
Ringtone — the plugin rings with the device ringtone and vibrates, following the phone's ringer mode (normal → sound + vibration, vibrate → vibration, silent → nothing); a volume-key press silences it. Custom sound: put a file in android/app/src/main/res/raw/ and set android.ringtoneSound: 'my_ring'; disable vibration with android.vibrate: false.
Managed mode (optional) — setup({ android: { selfManaged: false } }) uses the system dialer UI instead. Add READ_PHONE_STATE, READ_PHONE_NUMBERS and CALL_PHONE to your app manifest, request the phone permission, and have the user enable the calling account (openPhoneAccountSettings()).

Using it with `@capacitor/push-notifications`

Both plugins work together with no extra setup. Android delivers FCM to a single FirebaseMessagingService; ionic-callkit's service is declared with a higher priority, handles call pushes (type: incoming_call / call_ended) itself, and forwards every other message and token refresh to @capacitor/push-notifications, so your pushNotificationReceived / registration listeners keep firing. Both plugins see the same FCM token.

If your app has its own FirebaseMessagingService, remove the plugin's from the merged manifest and pass call messages to it:

<service android:name="io.kreador.callkit.CallMessagingService" tools:node="remove" />

if (io.kreador.callkit.CallMessagingService.handleRemoteMessage(this, remoteMessage)) return;

Web

Browsers have no system call UI, so on the web your app renders the call screen (e.g. an ion-modal or a /call/:id page). The web implementation tracks calls and fires the same events as native, so the same listeners drive it. Web gets no pushes: call displayIncomingCall() when your own signalling (WebSocket, LiveKit room event, …) reports a call.

// Web: your signalling reports an incoming call
await CallKit.displayIncomingCall({ callId, callerName: 'Alice' });
// → 'incomingCall' fires → the same listener opens your call page

registerVoipToken, getAudioRoutes, setAudioRoute and the Android settings helpers reject with "not implemented" on web.

iOS setup

Xcode → Signing & Capabilities: add Push Notifications and Background Modes → Voice over IP.
Create a VoIP Services certificate on developer.apple.com/certificates, download it and import it into Keychain Access.

Export it as .p12, then convert it for the test script:

openssl pkcs12 -in YOUR_CERTIFICATES.p12 -out app.pem -nodes -clcerts

iOS notes

Every VoIP push must show a call. iOS 13+ terminates apps that receive a VoIP push without reporting a call to CallKit. The plugin reports calls synchronously from the push. For pushes it can't show (not a call payload, call_ended for an unknown call, busy) it reports and immediately ends a call, which can appear briefly or as a missed call. Prefer sending call_ended over your signalling or a regular (non-VoIP) push when the app is running.
Answering from the lock screen does not open the app. CallKit keeps the call in the system UI; your app is running in the background, so start media on callAnswered without relying on the WebView being visible.
Call ids: CallKit needs UUIDs. Use UUIDs as callId if you can; other strings work too and are mapped internally.
Early PushKit registration (recommended): call CallKitVoip.start() in application(_:didFinishLaunchingWithOptions:) (import IonicCallkit with CocoaPods, import CallKitPlugin with SPM). The plugin also registers when it loads, but registering at launch means a VoIP push that starts the app doesn't wait for the WebView.
Audio: ios.audioSession.autoConfigure: false lets your media SDK own AVAudioSession; otherwise the plugin configures play-and-record with Bluetooth when CallKit activates the session.
Not available on iOS: backToForeground, openPhoneAccountSettings, openFullScreenIntentSettings (reject as unimplemented); setAvailable, setReachable are no-ops; showIncomingCallUi / silenceIncomingCall / checkReachability / hasActiveCall are Android-only events.

Usage

import { CallKit } from 'ionic-callkit';

// Register listeners first: events that happened while the app was starting
// (e.g. the user answered from the lock screen) are delivered as soon as you listen.
await CallKit.addListener('voipToken', ({ token }) => {
  // POST the token to your backend (PushKit token on iOS, FCM token on Android)
});

await CallKit.addListener('incomingCall', ({ callId, callerName }) => {
  router.navigate(['/call', callId]);
});

await CallKit.addListener('callAnswered', ({ callId }) => webrtc.startSession(callId));
await CallKit.addListener('callEnded', ({ callId }) => webrtc.endSession(callId));
await CallKit.addListener('callRejected', ({ callId }) => signalling.decline(callId));

await CallKit.setup({ appName: 'My App', supportsVideo: true });
await CallKit.requestPermissions();
await CallKit.registerVoipToken();

Outgoing:

await CallKit.startCall({ callId, calleeName: 'Bob', handle: '[email protected]' });
// …when the remote side picks up:
await CallKit.setCallActive({ callId });
// …when it hangs up:
await CallKit.reportEndCall({ callId, reason: CallEndReason.RemoteEnded });

A complete Ionic Angular demo lives in example/.

Cold starts, reachability and concurrency (Android)

Cold start: when a push wakes a killed app, events raised before your listeners exist (incomingCall, callAnswered from the lock screen, …) are queued natively, persisted, and delivered as soon as you add listeners. getInitialEvents() also returns them (oldest first) so you can route straight to the call screen at startup; call clearInitialEvents() once handled. Events marked restored: true come from a previous process that died before delivering them — Android has already dropped those calls.
Reachability watchdog: if a call is answered but your app never comes up to handle it, the plugin ends it after android.answerReachabilityTimeout ms (default 10000, 0 disables). Adding a callAnswered listener or calling setReachable() marks the app as ready.
Call state: setCallState({ callId, state }) reports dialing / ringing / active / held to the system; every change is emitted as callStateChanged.
One call at a time: setCanMakeMultipleCalls({ allow: false }) (or android.canMakeMultipleCalls: false) refuses a second incoming call with incomingCallFailed { error: 'busy' } and makes startCall reject — tell the caller "busy" from that event.

Backend contract

The plugin only produces tokens; your server sends the pushes. Never ship APNs / FCM credentials in the app.

Both platforms read the same keys:

| Key | Required | Notes | |---|---|---| | type | no | incoming_call (default) or call_ended (caller hung up / cancelled) | | callId | yes | Your call id; every event carries it | | callerName | no | Shown in the call UI | | handle | no | Number / user id; defaults to callerName | | hasVideo | no | "true" / "false" |

The legacy keys ConnectionId / Username are still accepted.

Use a new callId per call (a UUID is ideal — iOS uses it directly). Pushes are de-duplicated per call id, and a push for a call id that ended in the last 5 minutes is ignored, so retries and a call_ended that overtakes its incoming_call never ring a finished call.

iOS — APNs VoIP push (https://api.push.apple.com/3/device/<token>, headers apns-topic: <bundle>.voip, apns-push-type: voip, apns-priority: 10):

{
  "aps": { "alert": "Incoming call", "content-available": 1 },
  "type": "incoming_call",
  "callId": "abc-123",
  "callerName": "Alice",
  "hasVideo": "false"
}

iOS 13+ terminates apps that receive a VoIP push without reporting a call, so only send VoIP pushes for real incoming calls.

Android — FCM HTTP v1 (POST https://fcm.googleapis.com/v1/projects/<project>/messages:send). The message must be data-only (no notification block) with high priority, otherwise it will not reach the app while it is killed:

{
  "message": {
    "token": "<fcm token>",
    "android": { "priority": "high", "ttl": "30s" },
    "data": { "type": "incoming_call", "callId": "abc-123", "callerName": "Alice", "hasVideo": "false" }
  }
}

Test scripts

# iOS (needs app.pem in the current directory)
dev/sendVoip.sh <callId> <voipToken> <bundleId> [hasVideo] [callerName] [sandbox|production]

# Android (service account JSON from Firebase → Project settings → Service accounts)
dev/sendFcm.sh <service-account.json> <fcmToken> [callId] [callerName] [hasVideo]
dev/sendFcm.sh <service-account.json> <fcmToken> <callId> --end

For production APNs use api.push.apple.com; sending a sandbox token there returns BadDeviceToken.

Credits

The Android implementation is a port of livekit/react-native-callkeep (ISC, © The CallKeep Authors), adapted for Capacitor.

API

setup(...)

setup(options: CallSetupOptions) => Promise<void>

Configure the plugin. Call once at app start, before any other call method.

Android: registers the PhoneAccount with Telecom and stores the settings so that a push received while the app is killed can still ring.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | CallSetupOptions |

registerVoipToken()

registerVoipToken() => Promise<{ token: string; }>

Get the push token used to ring this device. iOS: PushKit VoIP token. Android: FCM registration token. Also emitted as the voipToken event (including on token refresh).

Returns: Promise<{ token: string; }>

unregisterVoipToken()

unregisterVoipToken() => Promise<void>

Stop receiving call pushes (Android: deletes the FCM token).

displayIncomingCall(...)

displayIncomingCall(options: IncomingCallOptions) => Promise<void>

Show the native incoming call UI. Normally triggered natively by a push; call it yourself when the call arrives over your own signalling channel.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | IncomingCallOptions |

answerCall(...)

answerCall(options: CallIdOptions) => Promise<void>

Answer a ringing call from your own UI. Emits callAnswered.

| Param | Type | | ------------- | ------------------------------------------------------- | | options | CallIdOptions |

rejectCall(...)

rejectCall(options: CallIdOptions) => Promise<void>

Decline a ringing call. Emits callRejected.

| Param | Type | | ------------- | ------------------------------------------------------- | | options | CallIdOptions |

startCall(...)

startCall(options: OutgoingCallOptions) => Promise<void>

Start an outgoing call. Emits callStarted.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | OutgoingCallOptions |

setCallActive(...)

setCallActive(options: CallIdOptions) => Promise<void>

Mark an outgoing call as connected (remote side picked up).

| Param | Type | | ------------- | ------------------------------------------------------- | | options | CallIdOptions |

setCallState(...)

setCallState(options: { callId: string; state: SettableCallState; }) => Promise<void>

Report the call's connection state to the system (callkeep's setConnectionState), e.g. dialing while your signalling connects, active once media flows. Emits callStateChanged.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------- | | options | { callId: string; state: SettableCallState; } |

endCall(...)

endCall(options: CallIdOptions) => Promise<void>

Hang up a call locally. Emits callEnded.

| Param | Type | | ------------- | ------------------------------------------------------- | | options | CallIdOptions |

endAllCalls()

endAllCalls() => Promise<void>

Hang up every call.

reportEndCall(...)

reportEndCall(options: ReportEndCallOptions) => Promise<void>

Report that a call ended for a reason other than the local user hanging up (remote hang-up, missed, answered elsewhere…). Does not emit callEnded.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | ReportEndCallOptions |

updateDisplay(...)

updateDisplay(options: UpdateDisplayOptions) => Promise<void>

Update the name / handle shown in the system call UI.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | UpdateDisplayOptions |

setMuted(...)

setMuted(options: { callId: string; muted: boolean; }) => Promise<void>

Update the mute state shown in the system UI. Emits muted. The plugin does not touch your media tracks — mute them in your WebRTC layer.

| Param | Type | | ------------- | ------------------------------------------------ | | options | { callId: string; muted: boolean; } |

setSpeaker(...)

setSpeaker(options: { on: boolean; callId?: string; }) => Promise<void>

Route audio to the loudspeaker or back to the earpiece. Emits speakerChanged.

| Param | Type | | ------------- | ---------------------------------------------- | | options | { on: boolean; callId?: string; } |

setOnHold(...)

setOnHold(options: { callId: string; hold: boolean; }) => Promise<void>

Put a call on hold / resume it. Emits held.

| Param | Type | | ------------- | ----------------------------------------------- | | options | { callId: string; hold: boolean; } |

sendDTMF(...)

sendDTMF(options: { callId: string; digits: string; }) => Promise<void>

Play DTMF digits on a call. Emits dtmf.

| Param | Type | | ------------- | ------------------------------------------------ | | options | { callId: string; digits: string; } |

getAudioRoutes()

getAudioRoutes() => Promise<{ routes: AudioRoute[]; }>

List available audio routes. Android and iOS.

Returns: Promise<{ routes: AudioRoute[]; }>

setAudioRoute(...)

setAudioRoute(options: { callId: string; route: AudioRouteType; }) => Promise<void>

Select an audio route. Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------- | | options | { callId: string; route: AudioRouteType; } |

setAvailable(...)

setAvailable(options: { available: boolean; }) => Promise<void>

Tell the ConnectionService whether the app can take calls (e.g. false while logged out) so the user doesn't get stuck in the native UI. Android only; no-op elsewhere.

| Param | Type | | ------------- | ------------------------------------ | | options | { available: boolean; } |

setReachable()

setReachable() => Promise<void>

Tell the plugin the JS layer is ready to handle calls. Android only. Adding a callAnswered listener counts as reachable too. Answered calls are ended if the app isn't reachable within android.answerReachabilityTimeout.

setCanMakeMultipleCalls(...)

setCanMakeMultipleCalls(options: { allow: boolean; }) => Promise<void>

Allow or refuse concurrent calls. When false, a new incoming call while another is in progress is refused and incomingCallFailed is emitted with error: 'busy', and startCall rejects. Persisted, so pushes handled while the app is killed respect it.

| Param | Type | | ------------- | -------------------------------- | | options | { allow: boolean; } |

getInitialEvents()

getInitialEvents() => Promise<{ events: InitialEvent[]; }>

Events that happened before JS attached (e.g. the call was answered from the lock screen during a cold start), oldest first. They are also delivered to listeners; use this to route directly at startup. Events with restored: true come from a previous app process that died before delivering them — their calls no longer exist. Kept until clearInitialEvents(). Android and iOS (empty on web).

Returns: Promise<{ events: InitialEvent[]; }>

clearInitialEvents()

clearInitialEvents() => Promise<void>

Forget the events returned by getInitialEvents().

hasPhoneAccount()

hasPhoneAccount() => Promise<{ value: boolean; }>

Whether the calling account is registered and enabled. Always true in self-managed mode. Android only.

Returns: Promise<{ value: boolean; }>

openPhoneAccountSettings()

openPhoneAccountSettings() => Promise<void>

Open the system "Calling accounts" screen (managed mode). Android only.

canUseFullScreenIntent()

canUseFullScreenIntent() => Promise<{ value: boolean; }>

Whether the app may show a full-screen incoming call over the lock screen. Android 14+ may revoke this. Android only.

Returns: Promise<{ value: boolean; }>

openFullScreenIntentSettings()

openFullScreenIntentSettings() => Promise<void>

Open the settings page to grant full-screen intents (Android 14+).

backToForeground()

backToForeground() => Promise<void>

Bring the app to the foreground (e.g. after answering from the lock screen). Android only; rejects as unimplemented on iOS, which doesn't allow it.

getActiveCalls()

getActiveCalls() => Promise<{ calls: ActiveCall[]; }>

Currently tracked calls.

Returns: Promise<{ calls: ActiveCall[]; }>

checkPermissions()

checkPermissions() => Promise<CallKitPermissionStatus>

Returns: Promise<CallKitPermissionStatus>

requestPermissions(...)

requestPermissions(options?: { permissions: CallKitPermissionType[]; } | undefined) => Promise<CallKitPermissionStatus>

| Param | Type | | ------------- | ------------------------------------------------------ | | options | { permissions: CallKitPermissionType[]; } |

Returns: Promise<CallKitPermissionStatus>

addListener('voipToken', ...)

addListener(eventName: 'voipToken', listenerFunc: (data: { token: string; }) => void) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | -------------------------------------------------- | | eventName | 'voipToken' | | listenerFunc | (data: { token: string; }) => void |