@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

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

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-incoming-call-kit` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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

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

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

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

getActiveCalls() => Promise<ActiveCallsResult>

checkPermissions() => Promise<IncomingCallPermissionStatus>

requestPermissions() => Promise<IncomingCallPermissionStatus>

requestFullScreenIntentPermission() => Promise<IncomingCallPermissionStatus>

getPluginVersion() => Promise<PluginVersionResult>

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

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

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

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

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

removeAllListeners() => Promise<void>