@capgo/capacitor-incoming-call-kit

Show a native incoming call screen from your Capacitor app: CallKit on iOS and high-priority notifications on Android that can open a full-screen call screen. Ring the user for VoIP calls, video calls and alerts that need an answer.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-incoming-call-kit in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-incoming-call-kit to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Incoming call UI: showIncomingCall() displays the native ringing screen.
• Call events: callEnded, callTimedOut and incomingCallDisplayed listeners, plus callAccepted and callDeclined on iOS and Android.
• Call tracking: getActiveCalls(), endCall() and endAllCalls().
• Permissions: checkPermissions(), requestPermissions() and requestFullScreenIntentPermission() for Android 14 and later.
• Platforms: iOS and Android. iOS uses CallKit. Android uses high-priority notifications that can raise a full-screen activity. Web is a basic stub.

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(...)
• endCall(...)
• endAllCalls(...)
• getActiveCalls()
• checkPermissions()
• requestPermissions()
• requestFullScreenIntentPermission()
• getPluginVersion()
• addListener('incomingCallDisplayed', ...)
• addListener('callAccepted', ...)
• addListener('callDeclined', ...)
• addListener('callEnded', ...)
• addListener('callTimedOut', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

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.

Returns: Promise<ShowIncomingCallResult>

endCall(...)

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

Ends a specific tracked call.

Returns: Promise<ActiveCallsResult>

endAllCalls(...)

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

Ends every tracked call.

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.

Returns: Promise<PluginListenerHandle>

addListener('callAccepted', ...)

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

Fired when the user accepts the call from native UI.

Returns: Promise<PluginListenerHandle>

addListener('callDeclined', ...)

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

Fired when the user declines the call from native UI.

Returns: Promise<PluginListenerHandle>

addListener('callEnded', ...)

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

Fired when a call ends through the API or a platform action.

Returns: Promise<PluginListenerHandle>

addListener('callTimedOut', ...)

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

Fired when an unanswered call reaches its configured timeout.

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Removes every native listener registered by the plugin.

Interfaces

ShowIncomingCallResult

Result payload for showIncomingCall().

IncomingCallRecord

Represents a currently tracked call.

ShowIncomingCallOptions

Common options used to present an incoming call.

AndroidIncomingCallOptions

Android-specific incoming call presentation options.

IOSIncomingCallOptions

iOS-specific incoming call presentation options.

ActiveCallsResult

Result payload for getActiveCalls().

EndCallOptions

Options for ending a single tracked call.

EndAllCallsOptions

Options for ending all tracked calls.

IncomingCallPermissionStatus

Result payload for permission checks.

PluginVersionResult

Plugin version payload.

PluginListenerHandle

IncomingCallEvent

Payload delivered by plugin listeners.

Type Aliases

IncomingCallState

Supported incoming call states.

'ringing' | 'accepted' | 'ended'

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'