Prise en main

Installation

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Utilisez ensuite le prompt suivant :

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

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

1. Installer le package

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

2. Synchroniser les projets natifs

   bunx cap sync

3. Choisissez votre source d'appel Décidez si l'événement incoming-call provient de votre backend, d'un SDK comme Twilio ou Stream, ou d'un flux de push natif tel que FCM ou PushKit.

Démarrage rapide

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

const result = await IncomingCallKit.showIncomingCall({
  callId: 'call-id-123',
  callerName: 'caller',
});
console.log(result);

Exemple : endCall

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

const result = await IncomingCallKit.endCall({ callId: 'call-id-123' });
console.log(result);

Exemple : endAllCalls

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

const result = await IncomingCallKit.endAllCalls();
console.log(result);

Erreurs courantes

• Autorisations: appelez checkPermissions() puis requestPermissions() si nécessaire.
• Écouteurs: supprimez les handles lors du démontage des écrans.
• Source de vérité : fiez-vous src/definitions.ts au repo GitHub.

Fonctionnement de l'intégration

Ce plugin gère uniquement l'affichage natif de l'appel entrant. Votre application reste responsable du transport, de l'authentification et de la session média elle-même.

Le schéma de production classique est :

1. Votre backend ou votre SDK d'appel émet un événement de sonnerie.
2. Votre application appelle showIncomingCall().
3. Le plugin affiche l'interface native d'appel entrant.
4. callAccepted indique à votre application de rejoindre la salle ou la session VoIP.
5. callDeclined, callEnded, ou 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: timeout de non-réponse (best-effort)
• extra: JSON arbitraire renvoyé dans les payloads du listener
• android.channelId et android.channelName: réglage du canal de notification Android
• android.showFullScreen: demande l'activité d'appel entrant plein écran sur Android
• ios.handleType: choisissez generic, phoneNumber, ou emailAddress pour CallKit

Gérer les 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énements

• incomingCallDisplayed : l'interface native s'est affichée avec succès
• callAccepted : l'utilisateur a accepté via l'interface 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 contient le call payload normalisé et votre extra objet.

Notes sur les plateformes

• Lire le Guide iOS avant d'intégrer CallKit dans un flux PushKit ou APNs.
• Lire le Guide Android avant de s'appuyer sur les full-screen intents sur Android 14 et versions ultérieures.
• Le Web n'est pas supporté.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier les opérations du dashboard et de API, connectez-l’avec Utilisation de @capgo/capacitor-incoming-call-kit pour la capacité native dans Utilisation de @capgo/capacitor-incoming-call-kit, Aperçu de API pour les détails d'implémentation dans « Vue d'ensemble de API », Introduction pour les détails d'implémentation dans l'introduction, Clés API pour les détails d'implémentation dans « Clés API », et Appareils pour les détails d'implémentation dans Devices.