WhatsApp Message Updated Webhook Examples

For the exhaustive schema-derived catalog, see all 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/1.1 200 OK

For endpoint setup, signature validation, and retry behavior, see 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

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/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.

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

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/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 beread, 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
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

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/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

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/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 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.
We do not charge you for failed messages.

Getting Started

Guides

Endpoints

Webhooks

WhatsApp Message Updated Webhook Examples

What it is

Before you begin

How it works

Request

Response

Message Sent

Request

Response

Explanation

Message Delivered

Request

Response

Explanation

Message Read

Request

Response

Explanation

Message Failed

Request

Response

Explanation

​What it is

​Before you begin

​How it works

​Request

​Response

​Message Sent

​Request

​Response

​Explanation

​Message Delivered

​Request

​Response

​Explanation

​Message Read

​Request

​Response

​Explanation

​Message Failed

​Request

​Response

​Explanation

What it is

Before you begin

How it works

Request

Response

Message Sent

Request

Response

Explanation

Message Delivered

Request

Response

Explanation

Message Read

Request

Response

Explanation

Message Failed

Request

Response

Explanation