Genuka WA docs

Conectar un agente de voz a las llamadas de WhatsApp

Recibe y realiza llamadas de WhatsApp con tu propio agente de voz o stack WebRTC: activar las llamadas, webhooks call.*, acciones de llamada con SDP, permisos.

Genuka WA retransmite las llamadas de WhatsApp a tu propio stack: un agente de voz, un softphone WebRTC, un centro de contacto. Activas las llamadas en el número, recibes cada llamada por webhook con su SDP y respondes a través de la API. El audio circula directamente entre Meta y tu stack; nunca pasa por Genuka WA. Las llamadas están incluidas a partir del plan Growth.

Última actualización: 17 de noviembre de 2026

Antes de empezar

  • El número debe ser elegible. Meta reserva las llamadas para los números con suficiente volumen de conversaciones, y excluye algunos países (entre ellos Estados Unidos, Canadá y Nigeria). Cuando no se cumple, Meta lo rechaza con su propio mensaje, que se devuelve tal cual (422).
  • Sin coexistencia. Un número compartido con la app WhatsApp Business no tiene llamadas por la API (409 calling_unavailable_coexistence).
  • Un webhook suscrito a las llamadas. Suscribe un endpoint a call.connect, call.status_changed, call.terminated y call.permission_replied (consulta Webhooks).

1. Activa las llamadas en el número

curl -X PATCH https://wa.genuka.com/api/v1/numbers/con_1/calling \
  -H "Authorization: Bearer pk_live_…" -H "Content-Type: application/json" \
  -d '{ "status": "ENABLED" }'

La página del número en el panel tiene el mismo interruptor. callHours limita las llamadas entrantes a tu horario de atención; con callbackPermissionStatus, un cliente que te llama te autoriza a devolverle la llamada.

2. Un cliente te llama

  1. Llega el webhook call.connect con data.callId, data.from (el cliente) y data.session.sdp, la oferta SDP del cliente.
  2. Tu stack construye su respuesta SDP y la envía de inmediato como pre_accept: el audio puede establecerse mientras el agente contesta.
  3. Cuando el agente esté listo, accept con la misma respuesta SDP.
  4. terminate para colgar. call.terminated llega en todos los casos, con la duración.
POST /api/v1/calls
{ "action": "pre_accept", "callId": "wacid.HBgL…", "sdp": "v=0\r\n… (tu respuesta SDP)" }

La llamada suena durante unos 30 segundos. Todo el recorrido, desde el webhook hasta tu pre_accept, tiene que caber en ese plazo: confirma el webhook de inmediato y procesa la llamada en paralelo. Basta con el callId, sin connectionId: Genuka WA sabe a qué número pertenece la llamada (si no, 404 call_not_found: pasa el connectionId).

Las suscripciones se basan en el campo de Meta

Los webhooks se filtran por campo de Meta: suscribirte a call.permission_replied también te trae los eventos message.*, ya que la respuesta es un mensaje. Filtra por el type del sobre. El bizOpaqueCallbackData de una acción de llamada vuelve como data.callbackData.

3. Llamas a un cliente

Meta exige el permiso del cliente antes de cualquier llamada saliente.

  1. Verifícalo: GET /api/v1/calls/permissions?waId=+237690000001&connectionId=con_1. Si canCall es verdadero, pasa al paso 3.

  2. Si no, y si canRequestPermission es verdadero, pídelo (dentro de la ventana de 24 horas):

    POST /api/v1/messages
    { "connectionId": "con_1", "to": "+237690000001",
      "callPermissionRequest": { "body": "We would like to call you back about your order." } }

    La respuesta del cliente llega como call.permission_replied. Meta limita cuántas veces puedes pedirlo por cliente y por día: canRequestPermission en falso significa esperar, no volver a pedirlo.

  3. Inicia la llamada con tu oferta SDP. La respuesta SDP del cliente llega en call.connect.

    POST /api/v1/calls
    { "connectionId": "con_1", "action": "connect", "to": "+237690000001", "sdp": "v=0\r\n… (tu oferta SDP)" }

Deja que el cliente te llame

Un botón de llamada de WhatsApp, en una conversación abierta, le permite al cliente llamarte con un solo toque:

POST /api/v1/messages
{ "connectionId": "con_1", "to": "+237690000001",
  "voiceCall": { "body": "Any question? Call us on WhatsApp.", "displayText": "Call" } }

Fuera de la ventana de 24 horas, usa una plantilla con un botón VOICE_CALL.

Errores que conviene conocer

EstadoerrorQué hacer
403plan_feature_unavailableCambia al plan Growth.
409calling_unavailable_coexistenceUsa un número que no esté compartido con la app WhatsApp Business.
400invalid_call_actionCorrige el cuerpo: la lista completa está en issues.
422meta_errorLee el mensaje de Meta: número no elegible, sin permiso, país excluido…

La referencia completa está en API · Llamadas de WhatsApp, y el SDK de TypeScript en Llamadas.

En esta página