Ejemplos de Webhook para terminación y captura de llamadas de WhatsApp

Para consultar el catálogo completo derivado del esquema, consulta todos los ejemplos.

Qué es

Gestiona eventos de terminación de llamadas, grabación y transcripción de WhatsApp.

Antes de comenzar

Crea un endpoint HTTPS público en tu aplicación.
Configura un endpoint de Webhook de YCloud para los tipos de eventos que necesites.
Almacena el secreto de firma del endpoint de forma segura.
Haz que el procesamiento de eventos sea idempotente.

Cómo funciona

YCloud envía una solicitud HTTP POST cuando ocurre el evento. Verifica la firma, registra el evento de forma duradera, devuelve una respuesta 2xx y procesa las tareas lentas de manera asíncrona.

Solicitud

Los escenarios a continuación muestran solicitudes enviadas a tu URL de Webhook. Trata el id del evento como el identificador de entrega y usa type para enrutar el payload.

Respuesta

Devuelve un estado 2xx después de aceptar el evento.

HTTP/1.1 200 OK

Para configurar el endpoint, validar la firma y conocer el comportamiento de reintento, consulta Configurar webhooks.

Tanto la empresa como el usuario de WhatsApp pueden finalizar la llamada en cualquier momento. Cuando la empresa o el usuario de WhatsApp finalizan la llamada, recibes un Webhook de finalización de llamada (Call Terminate):

Llamada completada

Solicitud

{
  "id": "evt_6757b889a5a42d369ef48481",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:42:01.822Z",
  "callingTerminate": {
    "id": "6757b889960b25543b9ecc67",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTE",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "fromUserId": "ID.13491208655302741918",
    "fromParentUserId": "ID.11815799212886844830",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733734738000,
    "endTime": 1733734771000,
    "duration": 33,
    "status": "COMPLETED"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, desduplícalo por id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.

Llamada fallida

Solicitud

{
  "id": "evt_675907f431c55113a751d0e7",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-11T03:33:08.679Z",
  "callingTerminate": {
    "id": "675907a13ae4a901f05fee95",
    "wacid": "wacid.HBgNODYxNTE1NzEzNzYyM",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "fromUserId": "ID.13491208655302741918",
    "fromParentUserId": "ID.11815799212886844830",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733826484000,
    "endTime": 1733826637000,
    "duration": 30,
    "status": "FAILED",
    "errorCode": "131000"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, desduplícalo por id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.

Grabación de llamada disponible

Para una llamada originada por API con la grabación activada, whatsapp.call.recording.updated informa la disponibilidad de la grabación o un fallo permanente en el procesamiento.

Solicitud

{
  "id": "evt_call_recording_01JZ8K4V7H3P6Q9R2T5W8X1Y4Z",
  "type": "whatsapp.call.recording.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-04T08:00:00.000Z",
  "callingRecording": {
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "mediaAssetId": "66b1f0c2e4b05c2d8f1a3b47",
    "status": "AVAILABLE"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Usa callingRecording.wacid para identificar la llamada y phoneId para identificar el número de teléfono de la empresa. Descarga mediaAssetId solo cuando status sea AVAILABLE. El procesamiento de la grabación es independiente del resultado de terminación de la llamada. Para FAILED, inspecciona error.code y error.retryable. Consulta grabaciones y transcripciones.

Error en la transcripción de la llamada

Para una llamada originada por API con la transcripción activada, whatsapp.call.transcription.updated informa la disponibilidad de la transcripción o un fallo permanente en el procesamiento.

Solicitud

{
  "id": "evt_call_transcription_01JZ8K5A9C4D7E0F3G6H9J2K5M",
  "type": "whatsapp.call.transcription.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-04T08:01:00.000Z",
  "callingTranscription": {
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "mediaAssetId": "66b1f0d9e4b05c2d8f1a3b48",
    "status": "FAILED",
    "error": {
      "code": "CALLING_TRANSCRIPTION_PROCESSING_FAILED",
      "retryable": false
    }
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Lee callingTranscription en lugar de callingRecording. En este ejemplo, status es FAILED y error.retryable es false. No intentes descargar el recurso fallido. Un resultado AVAILABLE utiliza mediaAssetId para la descarga; el resultado de la transcripción es independiente del resultado de la grabación y del estado de finalización de la llamada.

Primeros pasos

Guías

Endpoints

Webhooks

Ejemplos de Webhook para terminación y captura de llamadas de WhatsApp

Qué es

Antes de comenzar

Cómo funciona

Solicitud

Respuesta

Llamada completada

Solicitud

Respuesta

Explicación

Llamada fallida

Solicitud

Respuesta

Explicación

Grabación de llamada disponible

Solicitud

Respuesta

Explicación

Error en la transcripción de la llamada

Solicitud

Respuesta

Explicación

​Qué es

​Antes de comenzar

​Cómo funciona

​Solicitud

​Respuesta

​Llamada completada

​Solicitud

​Respuesta

​Explicación

​Llamada fallida

​Solicitud

​Respuesta

​Explicación

​Grabación de llamada disponible

​Solicitud

​Respuesta

​Explicación

​Error en la transcripción de la llamada

​Solicitud

​Respuesta

​Explicación

Qué es

Antes de comenzar

Cómo funciona

Solicitud

Respuesta

Llamada completada

Solicitud

Respuesta

Explicación

Llamada fallida

Solicitud

Respuesta

Explicación

Grabación de llamada disponible

Solicitud

Respuesta

Explicación

Error en la transcripción de la llamada

Solicitud

Respuesta

Explicación