We are sunsetting On-Premises API. Refer to our On-Premises API Sunset document for details, and to learn how to migrate to our next-generation Cloud API.
The WhatsApp Business API client sends notifications about the status
of the message between you and your users. These notifications are sent via the statuses
object.
For each message you send, a notification about the status of the message will be sent to your webhook callback. In the table below, click the arrow in the left column for the WhatsApp app equivalent to each status, if available.
Name | Description |
---|---|
| A message sent by the customer was deleted by the customer. Upon receiving this notification, you should ensure that the message is deleted from your system if it was downloaded from the server. |
| A message sent by you was delivered to the customer's device. |
| A message sent by you failed to send. A reason for the failure will be included in the callback. Check the error message documentation for help debugging:
|
| A message sent by you was read by the customer. |
| A message sent by you is in transit within our systems. For On-Premises API users: To receive notifications for |
| A message you sent contains an item in a catalog that is not available or does not exist. |
The order of these notifications in your app may not reflect the actual timing of the message status. View the timestamp to determine the timing, if necessary.
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.
Since February 1, 2022, the statuses
object in your outbound notifications include two new nested objects: conversation
and pricing
. The conversation and pricing object components vary depending on conversation category. See more information below:
In the following examples, the recipient_id
may instead be a group_id
field. It depends on whether the message is sent to an individual or to a group.
The following webhook is received when a business sends a message as part of a user-initiated conversation (if that conversation did not originate in a free entry point):
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "sent", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "expiration_timestamp": TIMESTAMP, "origin": { "type": "user_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "user_initiated" } }] }
The following webhook is received when a business sends a message as part of a user-initiated conversation for a media message (if that conversation did not originate in a free entry point):
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "sent", "timestamp": "TIMESTAMP", "type": "message", "message": { "media_id": "98d14c8e-0310-4061-8f99-2d148274c286", "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "expiration_timestamp": TIMESTAMP, "origin": { "type": "user_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "user_initiated" } }] }
The following webhook is received when a business sends a message as part of a business-initiated conversation:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "sent", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "expiration_timestamp": TIMESTAMP, "origin": { "type": "business_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "business_initiated" } }] }
The following webhook is received when a business sends a message in reply to a user-initiated conversation originating from free entry points:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "sent", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "expiration_timestamp": TIMESTAMP, "origin": { "type": "referral_conversion", } }, "pricing": { "pricing_model": "CBP", "billable": false, "category": "referral_conversion" } }] }
The following webhook is received when a business’ message is delivered and that message is part of a user-initiated conversation (if that conversation did not originate in a free entry point):
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "delivered", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "origin": { "type": "user_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "user_initiated" } }] }
The following webhook is received when a business’ message is delivered and that message is part of a business-initiated conversation:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "delivered", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id": "WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "origin": { "type": "business_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "business_initiated" } }] }
The following webhook is received when a business’ message is delivered and that message is part of a user-initiated conversation originating from a free entry point:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "delivered", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id": "WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "origin": { "type": "referral_conversion", } }, "pricing": { "pricing_model": "CBP", "billable": false, "category": "referral_conversion" } }] }
Standard callback for a message read:
{ "statuses":[{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "read", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id": "WHATSAPP_ID" } }] }
{ "statuses": [{ "errors": [{ "code": 470, "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider." }], "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "failed", "timestamp": "TIMESTAMP" }] }
{ "statuses": [{ "errors": [{ "code": 480, "title": "Failed to send message since we detect an identity change of the contact" }], "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "failed", "timestamp": "TIMESTAMP" }] }
The conversation subsection is not included in the callback, if a message has failed. No billing or conversation activation is involved in this case.
Standard callback for a deleted message:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "deleted", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id": "WHATSAPP_ID" } }] }
The conversation subsection is not included in the callback, if a message has been deleted. No billing or conversation activation is involved in this case.
See Overview, Messages for this information.
Yes, there is a specific scenario where you can get pricing information on your webhook alert for read messages. For each sent message, there can be 3 scenarios:
Scenario | When it Happens |
---|---|
You get a webhook alert when the message is delivered (including pricing information) and another webhook alert when the message is read (not including pricing information). | This is the most common scenario. |
You get a webhook alert when the message is delivered (including pricing information). You do not get a webhook alert that the message has been read. | Common when a customer has turned off the feature that lets people know they have read a message. |
You get a webhook alert when the message is read (including pricing information). You do not get a webhook alert that the message has been delivered. | Only triggered when the user is already reading the thread with the business when the message comes in. |