Ejemplos de webhook de mensaje de WhatsApp actualizado

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

Qué es

Comprende las actualizaciones de mensajes de WhatsApp enviados, entregados, leídos y fallidos.

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 forma asíncrona.

Solicitud

Los siguientes escenarios muestran solicitudes entregadas a tu URL de webhook. Trata el evento id como el identificador de entrega y utiliza type para enrutar el payload.

Respuesta

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

HTTP/1.1 200 OK

Para la configuración de endpoints, validación de firmas y comportamiento de reintentos, consulta Configurar webhooks.

Tras solicitar con éxito a la API el envío de mensajes, estos tendrán un estado de accepted. Las actualizaciones de estado del mensaje activarán el webhook whatsapp.message.updated. Por lo general, el estado del mensaje:

Cambia a failed si no podemos entregar este mensaje.
Cambia a sent si es posible entregar este mensaje, y más adelante puede cambiar a failed, delivered o read.
Cambia a delivered o read si este mensaje se entregó al dispositivo del destinatario.

Sin embargo, la situación real es compleja. En primer lugar, no garantizamos el orden de las notificaciones de webhook, especialmente cuando los eventos ocurren casi simultáneamente. En segundo lugar, los eventos delivered pueden ocurrir después de failed, y viceversa, especialmente cuando el usuario final utiliza varios dispositivos.

Mensaje enviado

En este caso, tu endpoint de webhook recibió un evento de mensaje sent:

El status del mensaje es sent, lo que significa que el mensaje está en tránsito dentro de los sistemas de WhatsApp.
Contiene información sobre la conversación, incluida la hora en que caduca la conversación y el tipo de origen.
Contiene el pricingCategory y la totalPrice estimados que podríamos cobrarte.
Contiene wamid, que es el ID del mensaje original en la plataforma de WhatsApp, comenzando con wamid..

Solicitud

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M."
    },
    "status": "sent",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Respuesta

Confirma la entrega después de aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

totalPrice es solo un precio estimado antes de que se entregue el primer mensaje, y se convierte en el precio final cuando el status es delivered o read. El saldo ocupado por aquellos mensajes que se envían pero aún no se han entregado no estará disponible hasta que se descarten los mensajes (los mensajes enviados que no se entreguen durante 30 días se descartan).
Por lo general, un mensaje sent cambia a delivered o read en poco tiempo, excepto si:
- La cuenta de WhatsApp del destinatario está sin conexión; los mensajes de WhatsApp enviados no se entregarán hasta que el destinatario disponga de servicios de internet activos o funcionales.
- Cualquier mensaje enviado a un contacto que te haya bloqueado siempre mostrará el mensaje sent y nunca cambiará a delivered.
- El destinatario ha desactivado las confirmaciones de lectura, por lo que no recibirás las confirmaciones de mensaje read.
- El mensaje cambia a failed más adelante con el código de error 131026, lo que significa “Message Undeliverable.” o “Receiver is incapable of receiving this message”. Lo más probable es que el destinatario no esté registrado o esté utilizando una versión antigua de WhatsApp.
- El mensaje no se entregó para preservar una experiencia de usuario de alta calidad. Consulta Límites de mensajes de plantillas de marketing por usuario.

Mensaje entregado

En este caso, tu endpoint de webhook recibió un evento de mensaje delivered:

El status del mensaje es delivered, lo que significa que el mensaje se entregó al dispositivo del destinatario.

Solicitud

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M.",
      "username": "@pablomorales"
    },
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "deliverTime": "2022-03-01T12:00:02.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Respuesta

Confirma la entrega después de aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Este evento indica que el mensaje enviado por tu empresa se entregó al dispositivo del usuario.
Para que un estado sea read, debe haber sido delivered. En algunos escenarios, como cuando un usuario se encuentra en la pantalla de chat y llega un mensaje, el mensaje se marca como delivered y read casi simultáneamente. En este u otros escenarios similares, no se devolverá la notificación de delivered, ya que se sobreentiende que un mensaje ha sido entregado si ha sido leído. La razón de este comportamiento es una optimización interna.
Es posible que generemos más de 1 evento de webhook de delivered para el mismo mensaje, especialmente si el usuario final utiliza varios dispositivos.
pricingModel: “PMP” — indica que se aplica el precio por mensaje. Consulta también whatsapp-message-pricing-updates
pricingType
- regular — indica que el mensaje es facturable.
- free_customer_service : indica que el mensaje es gratuito porque fue un mensaje de plantilla de utilidad o un mensaje sin plantilla enviado dentro de una ventana de servicio de atención al cliente.
- free_entry_point : indica que el mensaje es gratuito porque forma parte de una conversación de punto de entrada gratuito.

Mensaje leído

En este caso, tu endpoint de webhook recibió un evento de mensaje read:

El status del mensaje es read, lo que significa que el destinatario leyó el mensaje.

Solicitud

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M.",
      "username": "@pablomorales"
    },
    "status": "read",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "deliverTime": "2022-03-01T12:00:02.000Z",
    "readTime": "2022-03-01T12:00:02.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Si el destinatario ha desactivado las confirmaciones de lectura, no recibirás las confirmaciones read del mensaje.

Mensaje fallido

En este caso, tu endpoint de webhook recibió un evento de mensaje failed:

El status del mensaje es failed.
Contiene errroCode, errorMessage y whatsappApiError.

Solicitud

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "status": "failed",
    "errorCode": "100",
    "errorMessage": "Parameter Invalid",
    "whatsappApiError": {
      "message": "(#100) Invalid parameter",
      "type": "OAuthException",
      "code": "100",
      "fbtrace_id": "AwmiSOCojlAkqvjCTjGt37r",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Parameter Invalid"
      }
    },
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Estos eventos están diseñados para notificarte los cambios de estado de los mensajes salientes que enviaste previamente a los clientes.
El motivo del error en la mensajería suele ser que los parámetros de solicitud del mensaje no son válidos, el número de teléfono del cliente no está registrado, etc. Consulta también WhatsApp Errors para el manejo de errores.
whatsappApiError se proporciona si intentamos enviar este mensaje a la plataforma de WhatsApp de Meta para ayudarte a comprender los detalles del error. Consulta también Cloud API Error Codes.
No te cobramos por los mensajes fallidos.

Primeros pasos

Guías

Endpoints

Webhooks

Ejemplos de webhook de mensaje de WhatsApp actualizado

Qué es

Antes de comenzar

Cómo funciona

Solicitud

Respuesta

Mensaje enviado

Solicitud

Respuesta

Explicación

Mensaje entregado

Solicitud

Respuesta

Explicación

Mensaje leído

Solicitud

Respuesta

Explicación

Mensaje fallido

Solicitud

Respuesta

Explicación

​Qué es

​Antes de comenzar

​Cómo funciona

​Solicitud

​Respuesta

​Mensaje enviado

​Solicitud

​Respuesta

​Explicación

​Mensaje entregado

​Solicitud

​Respuesta

​Explicación

​Mensaje leído

​Solicitud

​Respuesta

​Explicación

​Mensaje fallido

​Solicitud

​Respuesta

​Explicación

Qué es

Antes de comenzar

Cómo funciona

Solicitud

Respuesta

Mensaje enviado

Solicitud

Respuesta

Explicación

Mensaje entregado

Solicitud

Respuesta

Explicación

Mensaje leído

Solicitud

Respuesta

Explicación

Mensaje fallido

Solicitud

Respuesta

Explicación