WhatsApp Message Updated Webhook Examples

🚧
Prerequisites
Make sure that your webhook endpoint is listening for whatsapp.message.updated events. See also Configure Webhooks, Retrieve a webhook endpoint API.

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

Code sample

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...",
    "status": "sent",
    "conversation": {
      "id": "00e5a7e14a588d96bd2343d105d03ec5",
      "originType": "marketing",
      "expireTime": "2023-02-23T12:00:00.000Z"
    },
    "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"
  }
}'

Note

There is a charge when the first business message with this conversation ID is delivered, initiating the 24 hour conversation session. 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).
conversation is included after the message is sent. conversation.expireTime is only an estimated time when the first message of this conversation is sent, and it will be refreshed when the first message of this conversation is delivered. See also Tracking Conversations.

The illustration below reflects an extreme example of conversation refreshing.
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.

Code sample

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...",
    "status": "delivered",
    "conversation": {
      "id": "00e5a7e14a588d96bd2343d105d03ec5",
      "type": "REGULAR",
      "originType": "marketing",
      "expireTime": "2023-02-23T12:00:00.000Z"
    },
    "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"
  }
}'

Note

There is a charge when the first business message with this conversation ID is delivered, initiating the 24 hour conversation session.
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.

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.

Code sample

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...",
    "status": "read",
    "conversation": {
      "id": "00e5a7e14a588d96bd2343d105d03ec5",
      "type": "REGULAR",
      "originType": "marketing",
      "expireTime": "2023-02-23T12:00:00.000Z"
    },
    "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"
  }
}'

Note

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.

Code sample

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...",
    "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"
  }
}'

Note

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.

🚧Prerequisites

Message Sent

Message Delivered

Message Read

Message Failed

🚧
Prerequisites