Ejemplos de webhook de estado de mensajes

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

Qué es

Gestiona actualizaciones de mensajes para WhatsApp, Messenger, Email, SMS y mensajes de Voice.

Antes de empezar

Crea un endpoint HTTPS público en tu aplicación.
Configura un endpoint de Webhook de YCloud para los tipos de eventos que necesites.
Guarda de forma segura el secreto de firma del endpoint.
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 el trabajo lento 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 usa type para enrutar el payload.

Respuesta

Devuelve un estado 2xx tras 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.

En el caso de WhatsApp, tras solicitar a la API el envío de mensajes con éxito, los mensajes tienen 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ó en el 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 mensaje status 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 expira la conversación y el tipo de origen.
Contiene el estimado pricingCategory y totalPrice que podríamos cobrarte.
Contiene wamid, que es el ID de mensaje original en la plataforma de WhatsApp, que comienza 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 tras 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 status es delivered o read. El saldo retenido por los mensajes enviados que no se han entregado no estará disponible hasta que se descarten los mensajes (los mensajes enviados que no se entregan durante 30 días se descartan).
Generalmente, un mensaje sent cambia pronto a delivered o read, excepto cuando:
- La cuenta de WhatsApp del destinatario está desconectada; los mensajes de WhatsApp que envíes no se entregarán hasta que el destinatario tenga servicios de internet activos o en funcionamiento.
- 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 los recibos de lectura de mensajes read.
- El mensaje cambia a failed más adelante con el código de error 131026, lo que significa “Message Undeliverable.”, o bien “Receiver is incapable of receiving this message”. Lo más probable es que el destinatario no esté registrado o esté utilizando una versión desactualizada de WhatsApp.
- El mensaje no se entregó para crear una experiencia de usuario de alta calidad. Consulta Per-User Marketing Template Message Limits.

Mensaje entregado

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

El mensaje status es delivered, lo que significa que el mensaje se entregó en el 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 tras 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ó en el dispositivo del usuario.
Para que un estado sea read, debe haber sido delivered. En algunos escenarios, como cuando un usuario está en la pantalla de chat y llega un mensaje, el mensaje se marca como delivered y read casi de forma simultánea. En este o en escenarios similares, la notificación delivered no se enviará de vuelta, ya que se sobreentiende que un mensaje ha sido entregado si ha sido leído. El motivo de este comportamiento responde a una optimización interna.
Es posible que generemos más de 1 evento de webhook 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 que no era de 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 clientes.
El motivo del fallo en el envío de mensajes suele ser que los parámetros de la solicitud del mensaje no son válidos, que el número de teléfono del cliente no está registrado, etc. Consulta también WhatsApp Errors para la gestión de errores.
Se proporciona whatsappApiError 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.

Actualización de entrega de correo electrónico

Usa email.delivery.updated cuando el estado de entrega de un correo electrónico cambie a delivered o failed.

Solicitud

{
  "id": "evt_example_email_delivery_updated",
  "type": "email.delivery.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "emailDelivery": {
    "emailId": "email_12345678",
    "recipientAddress": "customer@example.com",
    "status": "delivered",
    "externalId": "order_123"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Correlaciona la entrega con emailId y recipientAddress: el estado se aplica a este destinatario. Usa externalId cuando se proporcione para coincidir con tu propio registro. Inspecciona errorCode y errorMessage en una entrega fallida. La propiedad del payload es emailDelivery, no whatsappMessage.

Actualización de entrega de SMS

Usa sms.message.updated cuando el estado de entrega de un SMS cambie a delivered o undelivered.

Solicitud

{
  "id": "evt_example_sms_message_updated",
  "type": "sms.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "sms": {
    "id": "sms_12345678",
    "to": "+16315551111",
    "status": "delivered",
    "externalId": "order_123"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Identifica el SMS con sms.id y lee sms.status. Inspecciona errorCode cuando la entrega falle. SMS utiliza undelivered para un comprobante de entrega negativo; no apliques el modelo de estado read de WhatsApp a este evento.

Actualización de entrega de voz

Usa voice.message.updated cuando el estado de un mensaje de voz cambie a delivered o undelivered.

Solicitud

{
  "id": "evt_example_voice_message_updated",
  "type": "voice.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "voice": {
    "id": "voice_12345678",
    "to": "+16315551111",
    "status": "delivered",
    "externalId": "verification_123"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Identifica el mensaje de voz con voice.id y lee voice.status. Inspecciona errorCode cuando se proporcione. Este evento de entrega pertenece a la API de mensajería de voz; es independiente de los eventos del ciclo de vida de WhatsApp Calling.

Instantánea de lectura saliente de Messenger

Suscríbete a messenger.message.updated para instantáneas salientes individuales ordinarias guardadas. Un reintento de entrega conserva Event.id; volver a crear un evento a partir del mismo dato de origen puede generar un nuevo Event.id. Correlaciona las actualizaciones mediante messengerMessage.id.

Estados de envío y entrega

accepted significa que Meta aceptó el envío, no que el mensaje fue sent o delivered. rejected es un rechazo definitivo del envío; unknown es un resultado no confirmado y no debe tratarse como fallo. No reenvíes automáticamente un mensaje tras un tiempo de espera agotado o un resultado unknown. Comprueba su estado guardado usando un ID de mensaje devuelto cuando esté disponible, o contacta con soporte. Una instantánea conserva los datos actuales guardados, donde read tiene prioridad sobre delivered, sent y el resultado del envío. Las confirmaciones tardías no degradan ese estado. Puedes recibir instantáneas repetidas o perderte estados intermedios. Usa GET /v2/messenger/messages/{id} con from, o consulta por el ID de mensaje confirmado de Meta, para reconciliar tu estado guardado actual. Las notificaciones de resultados de envío son de mejor esfuerzo. No dependas de recibir un webhook para cada resultado de envío síncrono. Los ID opcionales, errorCode y las horas de confirmación se omiten cuando no están disponibles. Un error de envío almacenado puede permanecer presente después de que datos de confirmación posteriores establezcan un estado más sólido.

Solicitud

{
  "id": "evt_89abcdef0123456789abcdef",
  "type": "messenger.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:03.000Z",
  "messengerMessage": {
    "id": "1308528868252065792",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "from": "422500000000000",
    "to": "100800000000000",
    "type": "text",
    "text": {
      "body": "How can I help you?"
    },
    "status": "read",
    "createTime": "2026-10-20T02:00:00.000Z",
    "updateTime": "2026-10-20T02:00:03.000Z",
    "readTime": "2026-10-20T02:00:03.000Z"
  }
}

Respuesta

HTTP/1.1 200 OK

Explicación

El ID de la página de Facebook es from y el PSID del cliente es to. Este ejemplo expone el estado guardado read sin inventar información faltante de sendTime o deliverTime. id es el ID de mensaje de YCloud, mientras que metaMessageId es la identidad del proveedor.

Reacción a un mensaje de Messenger

Solicitud

{
  "id": "evt_abcdef0123456789abcdef01",
  "type": "messenger.message_reaction.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:04.000Z",
  "messengerMessageReaction": {
    "pageId": "422500000000000",
    "psid": "100800000000000",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "action": "react",
    "reaction": "love",
    "emoji": "❤️"
  }
}

Respuesta

HTTP/1.1 200 OK

Explicación

Usa pageId e psid para identificar la conversación, y metaMessageId para identificar el mensaje de destino. Una reacción es una interacción y no cambia el estado de entrega. Es posible que el destino no tenga un registro local del mensaje en YCloud. Conserva el createTime de origen; pueden producirse entregas repetidas. Verifica YCloud-Signature con el cuerpo sin procesar antes de devolver una respuesta correcta.

Reacción a un mensaje de Messenger retirada

Solicitud

{
  "id": "evt_bcdef0123456789abcdef012",
  "type": "messenger.message_reaction.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:05.000Z",
  "messengerMessageReaction": {
    "pageId": "422500000000000",
    "psid": "100800000000000",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "action": "unreact"
  }
}

Respuesta

HTTP/1.1 200 OK

Explicación

Elimina la reacción asociada a esta Página, al PSID del cliente y al mensaje de Meta de destino. unreact puede omitir reaction y emoji. No exijas un ID de mensaje local ni deduzcas un cambio en el estado del mensaje. Los reintentos de entrega HTTP mantienen el mismo ID de evento y cuerpo; las devoluciones de llamada repetidas de origen pueden crear un nuevo ID de evento. Verifica YCloud-Signature con el cuerpo sin procesar antes de devolver una respuesta correcta.

​Qué es

​Antes de empezar

​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

​Actualización de entrega de correo electrónico

​Solicitud

​Respuesta

​Explicación

​Actualización de entrega de SMS

​Solicitud

​Respuesta

​Explicación

​Actualización de entrega de voz

​Solicitud

​Respuesta

​Explicación

​Instantánea de lectura saliente de Messenger

​Estados de envío y entrega

​Solicitud

​Respuesta

​Explicación

​Reacción a un mensaje de Messenger

​Solicitud

​Respuesta

​Explicación

​Reacción a un mensaje de Messenger retirada

​Solicitud

​Respuesta

​Explicación

Qué es

Antes de empezar

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

Actualización de entrega de correo electrónico

Solicitud

Respuesta

Explicación

Actualización de entrega de SMS

Solicitud

Respuesta

Explicación

Actualización de entrega de voz

Solicitud

Respuesta

Explicación

Instantánea de lectura saliente de Messenger

Estados de envío y entrega

Solicitud

Respuesta

Explicación

Reacción a un mensaje de Messenger

Solicitud

Respuesta

Explicación

Reacción a un mensaje de Messenger retirada

Solicitud

Respuesta

Explicación