Iniciar sesiónEmpezar prueba gratis
Meta Tech Provider

Webhooks de llamadas de WhatsApp: eventos de la Calling API y llamadas en un número de Coexistencia

El campo calls del webhook reporta los eventos de la Calling API de WhatsApp Business: connect con una respuesta u oferta SDP, los estados de llamada RINGING, ACCEPTED y REJECTED, terminate con COMPLETED o FAILED y la duración, y call_recording_available o call_transcription_available. La guía de Coexistencia de Meta indica que las llamadas de voz y video no cambian en la app de WhatsApp Business y no son compatibles con la Cloud API, así que esas llamadas siguen en el teléfono.

easyCoexistence conecta el número de tu app de WhatsApp Business con la Cloud API de Meta mediante Coexistencia, para que tu IA y tus automatizaciones respondan mensajes y envíen plantillas mientras las llamadas siguen sonando en la app de tu teléfono.

Not supported

Llamadas de voz y video en la Cloud API para un número incorporado con la app de WhatsApp Business; en la app no cambian.

2,000

Límite mínimo diario de mensajes, en destinatarios únicos, que necesita un número antes de poder usar la Calling API.

7 days

Cuánto tiempo pueden descargarse las grabaciones y transcripciones de llamadas después de entregarse su webhook.

wacid

El prefijo de los ids de llamada, el valor que une los webhooks connect, de estado y terminate de una misma llamada.

whatsapp_business_messaging

El permiso que necesita una app para recibir webhooks de llamadas, el mismo que para los mensajes.

¿Qué informa el campo calls del webhook?

Todo lo que ocurre con una llamada realizada o recibida a través de la Calling API, en un solo campo con un evento por etapa. Una llamada iniciada por la empresa genera un evento connect, actualizaciones de estado y un evento terminate. Las llamadas gestionadas por SIP informan call_created en lugar de connect, sin la sesión SDP. Hay un evento relacionado que llega por otra vía: cuando un cliente responde a una solicitud de permiso de llamada, la respuesta llega en el campo messages como un mensaje interactivo de tipo call_permission_reply.

connectThe call is ready to connect; session carries the SDP to apply to your WebRTC stack.
call_createdA SIP call was attempted, business- or user-initiated.
statuses (type call)RINGING, ACCEPTED or REJECTED for a business-initiated call.
terminateThe call ended: status COMPLETED or FAILED, with times and duration when answered.
call_recording_availableA media id for the finished audio recording.
call_transcription_availableA media id for the transcript, a JSON document.

¿Cómo es un webhook de llamadas?

Tiene la misma estructura que cualquier webhook de WhatsApp, con un array calls dentro de value y field con el valor calls. direction indica BUSINESS_INITIATED o USER_INITIATED, from y to contienen los números de teléfono, to_user_id el BSUID del cliente, y cualquiera de los dos números puede faltar si el cliente usa un nombre de usuario. metadata.phone_number_id identifica tu número, como en cualquier otro campo. Este es el ejemplo de Call Connect de Meta, con los marcadores de posición tal como Meta los publica:

Meta's example: the Call Connect webhook
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315553601",
              "phone_number_id": "<PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<CALLEE_NAME>",
                  "username": "<USERNAME>"
                },
                "wa_id": "16315553602",
                "user_id": "<BSUID>",
                "parent_user_id": "<PARENT_BSUID>"
              }
            ],
            "calls": [
              {
                "id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
                "to": "16315553601",
                "to_user_id": "<BSUID>",
                "to_parent_user_id": "<PARENT_BSUID>",
                "from": "16315553602",
                "event": "connect",
                "timestamp": "1671644824",
                "direction": "BUSINESS_INITIATED",
                "session": {
                  "sdp_type": "answer",
                  "sdp": "<<RFC 8866 SDP>>"
                }
              }
            ]
          },
          "field": "calls"
        }
      ]
    }
  ]
}

¿Qué campos añade el evento terminate?

terminate es el evento que guardan la mayoría de los sistemas, porque cierra la llamada. Sus campos, según la referencia de Meta:

  • status: COMPLETED cuando la llamada terminó sin errores inesperados, incluidas las llamadas no contestadas; FAILED cuando no llegó a conectarse o se cortó.
  • start_time, end_time y duration en segundos: solo aparecen cuando la otra parte contestó.
  • errors: code, message, href y error_data.details en una llamada FAILED.
  • biz_opaque_callback_data: tu propia cadena de seguimiento, si enviaste una al iniciar o aceptar la llamada.

¿Funcionan los webhooks de llamadas en un número de Coexistencia?

La guía de Coexistencia de Meta lo responde en su tabla de funciones: las llamadas de voz y video no cambian en la app de WhatsApp Business y no son compatibles con la Cloud API para un número incorporado de esta forma. Los requisitos previos de la propia Calling API dicen lo mismo desde el otro lado: el número de la empresa debe estar en uso con la Cloud API, no con la app de WhatsApp Business. Por eso, en un número de Coexistencia los clientes siguen llamando como antes, la llamada suena en la app del teléfono y el campo calls no tiene nada que informar. Una empresa que necesita gestionar llamadas por software usa un número exclusivamente en la Cloud API.

¿Cómo se relacionan los eventos de una misma llamada?

Por el id de la llamada, que empieza con wacid y se repite en cada evento de esa llamada. Una llamada iniciada por la empresa informa connect con la respuesta SDP, los estados RINGING y después ACCEPTED o REJECTED, y por último terminate. Una llamada iniciada por el usuario informa connect con una oferta SDP que tu sistema debe responder, y luego terminate. Los eventos de grabación y transcripción, si están activados, llegan después de terminate. Guarda los eventos usando como clave id más event, ya que los reintentos los repiten y el orden de llegada no está garantizado. La lista completa de requisitos previos de la Calling API está en la página sobre llamadas en un número de Coexistencia.

¿Qué puede hacer tu IA con las llamadas en un número de Coexistencia?

Trabajar en el chat, mientras las llamadas siguen a cargo de la persona en el teléfono. easyCoexistence no se suscribe al campo calls y no tiene herramientas de llamadas; su conector y sus automatizaciones cubren mensajes y plantillas. En la práctica, una respuesta de la IA puede decirle al cliente cuándo hay alguien disponible para hablar y a qué número llamar, una automatización por palabra clave puede responder a «llamar» o «teléfono» con esa información, y el dueño atiende la llamada en la app de WhatsApp Business como siempre.

Errores comunes

  • Suscribirse a calls para un número de Coexistencia y esperar eventos. Meta indica que las llamadas no son compatibles con la Cloud API para estos números.
  • Esperar start_time y duration en todos los terminate. Solo aparecen cuando la llamada fue contestada; una llamada no contestada termina igualmente como COMPLETED.
  • Buscar las respuestas de permiso en el campo calls. Llegan en messages, como un mensaje interactivo call_permission_reply.
  • Dejar las grabaciones y transcripciones en Meta. Ambas se pueden descargar durante 7 días después de su webhook; luego desaparecen.
Hacerlo con EasyCoexistence

Cada número se monitorea 24/7, incluida la regla de los 14 días que desconecta un número cuya app no se abre. De US$ 9 a US$ 0.75 por número al mes, con un precio que baja a medida que añades números, y los primeros 3 días gratis.

Preguntas frecuentes

¿Los clientes pierden el botón de llamada cuando un número se conecta a la API mediante Coexistencia?

La guía de Coexistencia de Meta indica que las llamadas de voz y video no cambian en la app de WhatsApp Business. Los clientes llaman al mismo número y el dueño contesta en la app del teléfono.

¿La Calling API se cobra igual que los mensajes?

No. La página de precios de Meta indica que la Calling API tiene precios distintos y remite a un documento aparte de precios de llamadas, así que los cargos de llamadas no aparecen en el objeto pricing de los estados de mensajes.

¿Se puede grabar o transcribir una llamada de la Calling API?

Sí, si la grabación o la transcripción están activadas. Después de la llamada, Meta envía call_recording_available con un id de medio de audio o call_transcription_available con un id de documento JSON, normalmente en menos de un minuto.

¿Un webhook de llamadas puede ir a un endpoint distinto al de la app?

Sí. calls es uno de los campos que Meta permite dirigir a una URL de callback alternativa para una cuenta de WhatsApp Business o un número de teléfono, junto con messages y los campos de Coexistencia.

Sigue leyendo

¿Listo para empezar?

Configura WhatsApp Coexistence en minutos, no en meses. La app sigue funcionando en el teléfono.

Empezar prueba gratis

Verificado el