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.terminatedycall.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
- Llega el webhook
call.connectcondata.callId,data.from(el cliente) ydata.session.sdp, la oferta SDP del cliente. - Tu stack construye su respuesta SDP y la envía de inmediato como
pre_accept: el audio puede establecerse mientras el agente contesta. - Cuando el agente esté listo,
acceptcon la misma respuesta SDP. terminatepara colgar.call.terminatedllega en todos los casos, con la duración.
{ "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.
-
Verifícalo:
GET /api/v1/calls/permissions?waId=+237690000001&connectionId=con_1. SicanCalles verdadero, pasa al paso 3. -
Si no, y si
canRequestPermissiones 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:canRequestPermissionen falso significa esperar, no volver a pedirlo. -
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:
{ "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
| Estado | error | Qué hacer |
|---|---|---|
403 | plan_feature_unavailable | Cambia al plan Growth. |
409 | calling_unavailable_coexistence | Usa un número que no esté compartido con la app WhatsApp Business. |
400 | invalid_call_action | Corrige el cuerpo: la lista completa está en issues. |
422 | meta_error | Lee 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.
API de WhatsApp para agentes de IA: servidor MCP, llms.txt
Conecta Claude, Cursor o VS Code a la API de WhatsApp Business con el servidor MCP de Genuka WA, además de llms.txt, documentación en Markdown y una especificación OpenAPI.
Referencia de la API
Una sola API para controlarlo todo de forma programática: números, plantillas, mensajes, campañas y tu suscripción.