@capgo/capacitor-incoming-call-kit

v8.2.1

Published

20 days ago

Capacitor plugin for native incoming call UI with Android full-screen notifications and iOS CallKit.

0High
0Medium
0Low

riderx

capacitor plugin incoming-call callkit android ios voip

@capgo/capacitor-incoming-call-kit

Display a native incoming-call surface in Capacitor with Android full-screen notifications and iOS CallKit.

This plugin was built for teams who want something in the same space as olarewajuakeemope/capacitor-incoming-call-kit, but with a small API, typed events, clearer platform boundaries, and documentation you can actually ship from.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/incoming-call-kit/

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ |

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation. Only the latest major version is actively maintained.

Install

bun add @capgo/capacitor-incoming-call-kit
bunx cap sync

What This Plugin Does

Shows a native incoming call UI from JavaScript.
Emits buffered callAccepted, callDeclined, callEnded, and callTimedOut events so the action still reaches JS if the bridge was cold.
Uses Android notifications plus a full-screen activity.
Uses iOS CallKit for the system incoming-call sheet.
Keeps the push transport out of scope so you can wire it to your own FCM, PushKit, SIP, or backend flow.

What This Plugin Does Not Do

It does not register FCM, APNs, or PushKit for you.
It does not create or manage the underlying audio/video session.
It does not replace your VoIP SDK. It only handles the native incoming-call presentation layer.

Quick Start

import { IncomingCallKit } from '@capgo/capacitor-incoming-call-kit';

await IncomingCallKit.requestPermissions();
await IncomingCallKit.requestFullScreenIntentPermission();

await IncomingCallKit.addListener('callAccepted', async ({ call }) => {
  console.log('Accepted:', call.callId, call.extra);
  // Join your voice/video session here.
});

await IncomingCallKit.addListener('callDeclined', ({ call }) => {
  console.log('Declined:', call.callId);
});

await IncomingCallKit.addListener('callTimedOut', ({ call }) => {
  console.log('Timed out:', call.callId);
});

await IncomingCallKit.showIncomingCall({
  callId: 'call-42',
  callerName: 'Ada Lovelace',
  handle: '+39 555 010 020',
  appName: 'Capgo Phone',
  hasVideo: true,
  timeoutMs: 45_000,
  extra: {
    roomId: 'room-42',
    callerUserId: 'user_ada',
  },
  android: {
    channelId: 'calls',
    channelName: 'Incoming Calls',
    showFullScreen: true,
  },
  ios: {
    handleType: 'phoneNumber',
  },
});

Event Model

incomingCallDisplayed: native UI was shown successfully.
callAccepted: the user accepted from the native UI.
callDeclined: the user declined before joining.
callEnded: your app or the platform ended the tracked call.
callTimedOut: the call stayed unanswered until timeoutMs.

Each event carries the normalized call payload and your original extra object.

Platform Notes

Android

requestPermissions() requests POST_NOTIFICATIONS on Android 13+.
requestFullScreenIntentPermission() opens the Android 14+ settings page for full-screen intents.
showIncomingCall() posts a high-priority notification and can raise a full-screen activity while the app is already running.
The timeout is best-effort and also uses the notification timeout when available.

iOS

showIncomingCall() reports the call to CallKit.
CallKit itself does not require a runtime permission prompt, so requestPermissions() resolves immediately on iOS.
Your app is responsible for starting the real call session after callAccepted.
If you need background incoming-call delivery from VoIP pushes, wire your PushKit/APNs flow to call this plugin as soon as your Capacitor bridge is available.

Choosing An Architecture

If your app already uses Twilio, Stream, Daily, or a SIP stack, use this plugin as the native ringing layer and keep the media session in your existing SDK.
If you only need foreground testing or a custom backend event, calling showIncomingCall() directly from JS is enough.
If you need true background delivery, pair this plugin with your own native push integration instead of baking a push provider into the plugin itself.

Example App

The repository includes example-app with a small control panel for:

requesting permissions,
showing a demo incoming call,
inspecting active calls,
and watching listener payloads in real time.

API

Capacitor API for presenting a native incoming-call surface.

showIncomingCall(...)

showIncomingCall(options: ShowIncomingCallOptions) => Promise<ShowIncomingCallResult>

Displays the native incoming call UI.

Android shows a high-priority notification and can raise a full-screen activity. iOS reports the call to CallKit.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | ShowIncomingCallOptions |

Returns: Promise<ShowIncomingCallResult>

endCall(...)

endCall(options: EndCallOptions) => Promise<ActiveCallsResult>

Ends a specific tracked call.

| Param | Type | | ------------- | --------------------------------------------------------- | | options | EndCallOptions |

Returns: Promise<ActiveCallsResult>

endAllCalls(...)

endAllCalls(options?: EndAllCallsOptions | undefined) => Promise<ActiveCallsResult>

Ends every tracked call.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | EndAllCallsOptions |

Returns: Promise<ActiveCallsResult>

getActiveCalls()

getActiveCalls() => Promise<ActiveCallsResult>

Returns the currently tracked calls.

Returns: Promise<ActiveCallsResult>

checkPermissions()

checkPermissions() => Promise<IncomingCallPermissionStatus>

Returns the current permission state for notifications and full-screen intents.

Returns: Promise<IncomingCallPermissionStatus>

requestPermissions()

requestPermissions() => Promise<IncomingCallPermissionStatus>

Requests the notification permission when the platform supports it.

iOS CallKit itself does not require a runtime prompt, so iOS resolves without prompting.

Returns: Promise<IncomingCallPermissionStatus>

requestFullScreenIntentPermission()

requestFullScreenIntentPermission() => Promise<IncomingCallPermissionStatus>

Opens the Android 14+ full-screen intent settings page when available.

On other platforms this resolves with the current permission status.

Returns: Promise<IncomingCallPermissionStatus>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the native implementation version marker.

Returns: Promise<PluginVersionResult>

addListener('incomingCallDisplayed', ...)

addListener(eventName: 'incomingCallDisplayed', listenerFunc: (event: IncomingCallEvent) => void) => Promise<PluginListenerHandle>

Fired after the call has been handed to the native platform UI.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------- | | eventName | 'incomingCallDisplayed' | | listenerFunc | (event: IncomingCallEvent) => void |