> ## 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.
# WhatsApp Message Updated Webhook Examples
> Understand sent, delivered, read, and failed WhatsApp message updates.
For the exhaustive schema-derived catalog, see [all examples](/en/api-reference/guides/examples/webhook-examples/webhook-payload-examples).
## What it is
Understand sent, delivered, read, and failed WhatsApp message updates.
## Before you begin
* Create a public HTTPS endpoint in your application.
* Configure a YCloud webhook endpoint for the event types you need.
* Store the endpoint signing secret securely.
* Make event processing idempotent.
## How it works
YCloud sends an HTTP `POST` request when the event occurs. Verify the signature, durably record the event, return a `2xx` response, and process slow work asynchronously.
## Request
The scenarios below show requests delivered to your webhook URL. Treat the event `id` as the delivery identifier and use `type` to route the payload.
## Response
Return a `2xx` status after accepting the event.
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
For endpoint setup, signature validation, and retry behavior, see [Configure webhooks](/en/api-reference/guides/api-fundamentals/configure-webhooks).
After successfully requesting the API to send messages, messages have a status of `accepted`. Message status updates will trigger the `whatsapp.message.updated` webhook.
Typically, the message status:
* Changes to `failed` if we are unable to deliver this message.
* Changes to `sent` if it's possible to deliver this message, and later it may change to `failed`, `delivered`, or `read`.
* Changes to `delivered` or `read` if this message was delivered to the recipient's device.
But the actual situation is complex. First, we do not guarantee the order of webhook notifications, especially when the events occur almost simultaneously. Second, `delivered` events may happen after `failed`, and vice versa, especially when the end user is using multiple devices.
## Message Sent
In this case, your webhook endpoint received a message `sent` event:
* The message `status` is `sent`, which means the message is in transit within WhatsApp's systems.
* Contains information about the conversation, including the time when the conversation expires, and the origin type.
* Contains the **estimated** `pricingCategory` and `totalPrice` we may charge you.
* Contains `wamid`, which is the original message ID on WhatsApp’s platform, starting with `wamid.`.
### Request
```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"
}
}'
```
### Response
Acknowledge the delivery after durably accepting the event.
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### Explanation
* **`totalPrice` is only an estimated price before the first message is delivered, and it becomes the final price when the `status` is `delivered` or `read`. The balance taken up by those messages that are sent but haven't been delivered will not be available until the messages are dropped (Sent messages that are not delivered for 30 days are dropped).**
* Generally, a `sent` message changes to `delivered` or `read` soon, except:
* The recipient's WhatsApp account is offline, your sent WhatsApp messages won’t be delivered until the recipient has working or active internet services.
* Any message sent to a contact who has blocked you will always show the message `sent`, and will never change to `delivered`.
* The recipient has turned off read receipts, and you won’t receive the message `read` receipts.
* The message changes to `failed` later with error code `131026`, which means "Message Undeliverable.", or "Receiver is incapable of receiving this message". This is most likely that the recipient is not registered, or is using an old WhatsApp version.
* The message was not delivered to create a high quality user experience. See [Per-User Marketing Template Message Limits](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates#per-user-marketing-template-message-limits).
## Message Delivered
In this case, your webhook endpoint received a message `delivered` event:
* The message `status` is `delivered`, which means the message was delivered to the recipient's device.
### Request
```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"
}
}'
```
### Response
Acknowledge the delivery after durably accepting the event.
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### Explanation
* This event indicates that the message sent by your business was delivered to the user’s device.
* **For a status to be`read`, it must have been `delivered`. In some scenarios, such as when a user is in the chat screen and a message arrives, the message is `delivered` and `read` almost simultaneously. In this or other similar scenarios, the `delivered` notification will not be sent back, as it is implied that a message has been delivered if it has been read. The reason for this behavior is internal optimization.**
* It's possible for us to generate more than 1 `delivered` webhook event for the same message, especially if the end user is using multiple devices.
* **pricingModel**: "PMP"— indicates per-message pricing applies. See also [whatsapp-message-pricing-updates](https://docs.ycloud.com/reference/whatsapp-message-pricing-updates)
* **pricingType**
* **regular** — indicates the message is billable.
* **free\_customer\_service** — indicates the message is free because it was either a utility template message or non-template message sent within a customer service window.
* **free\_entry\_point** — indicates the message is free because it is part of a free-entry point conversation.
## Message Read
In this case, your webhook endpoint received a message `read` event:
* The message `status` is `read`, which means the message was read by the recipient.
### Request
```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"
}
}'
```
### Response
Acknowledge the delivery after durably accepting the event.
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### Explanation
* If the recipient has turned off read receipts, you won’t receive the message `read` receipts.
## Message Failed
In this case, your webhook endpoint received a message `failed` event:
* The message `status` is `failed`.
* Contains `errroCode`, `errorMessage`, and `whatsappApiError`.
### Request
```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"
}
}'
```
### Response
Acknowledge the delivery after durably accepting the event.
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### Explanation
* These events are intended to notify you of status changes for outbound messages you've previously sent to customers.
* The reason for the messaging failure is typically the message request parameters are invalid, the customer's phone number is not registered, etc. See also [WhatsApp Errors](https://docs.ycloud.com/reference/whatsapp-errors) for error handling.
* `whatsappApiError` is provided if we tried to submit this message to Meta's WhatsApp platform to help you understand the error details. See also [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
* We do not charge you for failed messages.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.