Primeros pasos

Instalación

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

1. Instala el paquete

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

2. Sincronizar proyectos nativos

   bunx cap sync

3. Elige tu fuente de llamada Decide si el evento incoming-call proviene de tu backend, de un SDK como Twilio o Stream, o de una ruta de push nativa como FCM o PushKit.

Inicio rápido

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

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

Ejemplo: endCall

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

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

Ejemplo: endAllCalls

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

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

Errores comunes

• Permisos: llama a checkPermissions() luego requestPermissions() cuando sea necesario.
• Listeners: elimina los handles cuando se desmonten las pantallas.
• Fuente de verdad: confianza src/definitions.ts en el repo de GitHub.

Cómo encaja la integración

Este plugin solo gestiona la presentación nativa de la llamada entrante. Tu app sigue siendo la dueña del transporte, la autenticación y la sesión de medios.

El patrón común en producción es:

1. Tu backend o el SDK de llamadas emite un evento de timbrado.
2. Tu app llama a showIncomingCall().
3. El plugin muestra la interfaz nativa de llamada entrante.
4. callAccepted le indica a tu app que se una a la sala o sesión VoIP real.
5. callDeclined, callEnded, o callTimedOut le indica a tu app que limpie el estado remoto.

Integración mínima

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

Opciones importantes

• callId: identificador estable reutilizado después con endCall()
• timeoutMs: timeout best-effort de no respuesta
• extra: JSON arbitrario devuelto en los payloads del listener
• android.channelId y android.channelName: ajuste del canal de notificaciones de Android
• android.showFullScreen: solicita la activity Android de llamada entrante a pantalla completa
• ios.handleType: elige generic, phoneNumber, o emailAddress para CallKit

Gestión de llamadas activas

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

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

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

Modelo de eventos

• incomingCallDisplayed: la interfaz nativa se mostró correctamente
• callAccepted: el usuario aceptó desde la interfaz nativa
• callDeclined: el usuario rechazó antes de unirse
• callEnded: tu app o la plataforma finalizaron la llamada
• callTimedOut: la llamada permaneció sin responder hasta timeoutMs

Cada evento incluye los datos normalizados de call payload normalizado y tu extra object.

Notas de plataforma

• Lee la Guía para iOS antes de integrar CallKit en un flujo de PushKit o APNs.
• Lee la Guía para Android antes de depender de full-screen intents en Android 14 y versiones posteriores.
• Web no es compatible.

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar las operaciones del dashboard y de API, conéctalo con Uso de @capgo/capacitor-incoming-call-kit para la capacidad nativa en Uso de @capgo/capacitor-incoming-call-kit, Resumen de API para los detalles de implementación en API Overview, Introducción para los detalles de implementación en la Introducción, Claves de API para los detalles de implementación en las claves de API, y Dispositivos para el detalle de implementación en Devices.