> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Ejemplos de webhook de mensaje de WhatsApp actualizado
> Comprende las actualizaciones de mensajes de WhatsApp enviados, entregados, leídos y fallidos.
Para consultar el catálogo exhaustivo derivado del esquema, consulta [todos los ejemplos](/es/api-reference/guides/examples/webhook-examples/webhook-payload-examples).
## 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
Para la configuración de endpoints, validación de firmas y comportamiento de reintentos, consulta [Configurar webhooks](/es/api-reference/guides/api-fundamentals/configure-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
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates#per-user-marketing-template-message-limits).
## 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
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.ycloud.com/reference/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
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.ycloud.com/reference/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](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
* No te cobramos por los mensajes fallidos.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.