Démarrage

1. Installez le package

   bun add @capgo/capacitor-incoming-call-kit

2. Synchroniser les projets natifs

   bunx cap sync

3. Choisissez votre source de signal Décidez si l'événement d'appel entrant provient de votre backend, d'un SDK tel que Twilio ou Stream, ou d'un chemin de push natif tel que FCM ou PushKit.

Comment l'intégration s'articule

Ce plugin ne gère que la présentation des appels entrants natifs. Votre application conserve la gestion du transport, de l'authentification et de la session média réelle.

Le modèle de production courant est :

1. Votre backend ou votre appel SDK émet un événement de sonnerie.
2. Votre application appelle showIncomingCall().
3. Le plugin présente une interface utilisateur native pour les appels entrants.
4. callAccepted indique à votre application de rejoindre la salle réelle ou la session VoIP.
5. callDeclined, callEndedou callTimedOut indique à votre application de nettoyer l'état distant.

Intégration minimale

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);
  // Start or join your real call session here.
});

await IncomingCallKit.addListener('callDeclined', ({ call }) => {
  console.log('Declined', call.callId);
  // Tell your backend or SDK that the user declined.
});

await IncomingCallKit.addListener('callTimedOut', ({ call }) => {
  console.log('Timed out', call.callId);
  // Clear ringing state in your backend or SDK.
});

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',
  },
});

Options importantes

• callId: identifiant stable réutilisé plus tard avec endCall()
• timeoutMs: temps d'attente de bon fonctionnement non répondu
• extra: JSON arbitraire renvoyé dans les payloads des écouteurs
• android.channelId et android.channelName: réglage du canal de notification Android
• android.showFullScreen: demande l'activité d'appel entrant plein écran Android
• ios.handleTypechoisissez generic, phoneNumber, ou emailAddress pour CallKit

Gestion des appels actifs

const { calls } = await IncomingCallKit.getActiveCalls();

await IncomingCallKit.endCall({
  callId: 'call-42',
  reason: 'remote-ended',
});

await IncomingCallKit.endAllCalls({
  reason: 'session-reset',
});

Modèle d'événement

• incomingCallDisplayed: l'interface utilisateur native a été affichée avec succès
• callAccepted: l'utilisateur a accepté depuis l'interface utilisateur native
• callDeclined: l'utilisateur a refusé avant de rejoindre
• callEnded: votre application ou la plateforme a terminé l'appel suivi
• callTimedOut: l'appel est resté sans réponse jusqu'à timeoutMs

Chaque événement transporte le payload normalisé call et votre objet original. extra Remarques de la plateforme

Section intitulée « Remarques de la plateforme »

• remarques de la plateforme guide iOS avant de brancher CallKit dans un flux PushKit ou APNs.
• Lisez le guide Android avant de compter sur les intentions d'écran plein écran sur Android 14 et ultérieurs.
• La version Web n'est pas prise en charge.