Webhooks are triggered when a customer performs an action or the status for a message a business sends a customer changes. You get a webhooks notification:
When a customer performs an action
|
|
When the status for a message received by a business changes (includes pricing information)
|
|
|
The notification payload is a combination of nested objects of JSON arrays and objects that contain information about a change.
Example Notification Payload { "object": "whatsapp_business_account", "entry": [{ "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "PHONE-NUMBER", "phone_number_id": "PHONE-NUMBER-ID" }, # Additional arrays and objects "contacts": [{...}] "errors": [{...}] "messages": [{...}] "statuses": [{...}] }, "field": "messages" }] }] } | The Nested Structure of the Notification Payload |
Name | Description |
---|---|
| The specific webhook a business is subscribed to. The webhook is |
| An array of entry objects. Entry objects have the following properties:
|
The value
object contains details for the change that triggered the webhook. This object is nested within the changes
array of the entry
array.
Name | Description |
---|---|
| Array of contact objects with information for the customer who sent a message to the business. Contact objects have the following properties:
|
| An array of error objects describing the error. Error objects have the following properties, which map to their equivalent properties in API error response payloads. Webhooks triggered by v15.0 and older requests:
Webhooks triggered by v16.0 and newer requests:
|
| Product used to send the message. Value is always |
| Information about a message received by the business that is subscribed to the webhook. See Messages Object. |
| A metadata object describing the business subscribed to the webhook. Metadata objects have the following properties:
|
| Status object for a message that was sent by the business that is subscribed to the webhook. See Statuses Object. |
The messages
array of objects is nested within the value
object and is triggered when a customer updates their profile information or a customer sends a message to the business that is subscribed to the webhook.
Name | Description | ||
---|---|---|---|
| When the
| ||
| When the
| ||
| Context object. Only included when a user replies or interacts with one of your messages. Context objects can have the following properties:
| ||
| A document object. When
| ||
| An array of error objects describing the error. Error objects have the following properties, which map to their equivalent properties in API error response payloads. Webhooks triggered by v15.0 and older requests:
Webhooks triggered by v16.0 and newer requests:
| ||
| The customer's WhatsApp ID. A business can respond to a customer using this ID. This ID may not match the customer's phone number, which is returned by the API as | ||
| The ID for the message that was received by the business. You could use messages endpoint to mark this specific message as read. | ||
| An identity object. Webhook is triggered when a customer's phone number or profile information has been updated. See
| ||
| When
| ||
| When a customer has interacted with your message, this object is included in the
| ||
| Included in the
| ||
| Referral object. When a customer clicks an ad that redirects to WhatsApp, this object is included in the
The referral object can be included in the following types of message: text, location, contact, image, video, document, voice, and sticker. Click-to-WhatsApp ads are only supported in the Android and iOS apps. If the customer is using the Web browser or their computer to click on an ad, then the resulting webhook will contain a | ||
| When
| ||
| When
| ||
| When
| ||
| Unix timestamp indicating when the WhatsApp server received the message from the customer. | ||
| The type of message that has been received by the business that has subscribed to Webhooks. Possible value can be one of the following:
| ||
| When
|
The statuses
object is nested within the value
object and is triggered when a message is sent or delivered to a customer or the customer reads the delivered message sent by a business that is subscribed to the Webhooks.
Name | Description |
---|---|
biz_opaque_callback_data string | Arbitrary string included in sent message. See Message object. |
conversation object | Information about the conversation.
See Conversations for more information about conversations and conversation categories. |
| An array of error objects describing the error. Error objects have the following properties, which map to their equivalent properties in API error response payloads. Webhooks triggered by v15.0 and older requests:
Webhooks triggered by v16.0 and newer requests:
|
id string | The ID for the message that the business that is subscribed to the webhooks sent to a customer |
pricing object | An object containing pricing information.
See Conversations for more information about conversations and conversation categories. |
recipient_id string | The customer's WhatsApp ID. A business can respond to a customer using this ID. This ID may not match the customer's phone number, which is returned by the API as |
status string |
|
timestamp Unix timestamp | Date for the status message |
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.