# Conectar un agente de voz a las llamadas de WhatsApp

URL: https://wa.genuka.com/es/docs/guides/voice-agent
Language: Spanish

> 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](https://wa.genuka.com/es/docs/webhooks)).

## 1. Activa las llamadas en el número

```bash
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.

```json title="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`).

> [!NOTE]
> **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):

   ```json title="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`.

   ```json title="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:

```json title="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

| 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](https://wa.genuka.com/es/docs/api#llamadas-de-whatsapp), y el
SDK de TypeScript en [Llamadas](https://wa.genuka.com/sdk/calling).
