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.
Webhooks have a top level array field indicating what is being communicated. The members of the array are JSON objects with detailed fields relevant to the Webhook.
WhatsApp Business API webhooks can contain the following objects:
messages
ObjectThe messages
object contains the following components:
Name | Description |
---|---|
type: Array of contact profile information | Provides all the information about the contact —see Inside |
type: Array of any type of message objects | Provides all of the information about the incoming message —see Inside |
type: string | WhatsApp ID of recipient |
When there are any out-of-band errors that occur in the normal operation of the application, the This type of error can be caused by transient network connectivity errors, invalid credentials, management controllers in unavailable status, etc. See Errors and Status Messages for more information. |
contacts
The contacts
object provides all the information about the contact.
This object only applies to text, contacts, and location messages. It is not currently supported for media messages and is not applicable for system messages.
Name | Description |
---|---|
type: Profile object | Contains the sender's profile information. |
type: String | The WhatsApp ID of the contact. |
profile
This object contains the sender's profile information.
Name | Description |
---|---|
type: String | Optional. Contains the sender's profile name. |
messages
The messages
object provides all of the information about the incoming message.
Name | Description |
---|---|
type: String | Optional. This object will only be included when someone replies to one of your messages. Contains information about the content of the original message, such as the ID of the sender and the ID of the message. See |
type: String | WhatsApp ID of the sender. |
type: String | Message ID. This ID can be used to mark a message as read. |
type: Identity Object | Optional. This object will only be included when the |
type: String | Message received timestamp. |
type: String | Message type. *If a user sends a disappearing message to the business, the businesses gets notified via a webhooks notification with type set to |
type: Message type objects that provide more information about the received message. | Message contents. See the |
type: Referral Object | Optional. This object is present when the user clicks on an ad that Clicks to WhatsApp and sends a message to the business. See referral Property. |
type: System Object | Notifications of changes to the system. |
type: Interactive Object | This object is present for notifications related to interactive messages. See |
context
A context
object is found in messages when a user replies or interacts with one of your messages. A user interacts with a message by inquiring for more information. context
objects for interactions do not have the from
and id
fields, as shown in this example.
Name | Description |
---|---|
type: String | Optional. Will not be present if the user only interacts with the message. WhatsApp ID of the sender of the original message. |
type: String | Optional. Will not be present if the user only interacts with the message. Message ID of original message. |
type: object | Used for enquiries coming from a Product Detail Page, Single Product Messages, and Multi-Product Message. |
referred_product
Used for Single Product Messages. This object contains the item mentioned in the message.
Name | Description |
---|---|
| ID for the catalog the item belongs to. |
| Unique identifier (in the catalog) of the product. |
identity
The identity
object provides all the information about the user's identity.
Applies to all incoming messages only when the show_security_notifications
parameter is set to true
in the application settings.
Name | Description |
---|---|
type: String | State of acknowledgment for latest |
type: Int | Timestamp of when the WhatsApp Business API client detected the user potentially changed. |
type: String | Identifier for the latest |
text
When the notification describes a text message, the text
object provides the body of the text message.
Name | Description |
---|---|
type: String | Message text. |
location
When you receive a notification of a user's static location, the location
object provides the details of the location.
Name | Description |
---|---|
type: Number | Latitude of location being sent. |
type: Number | Longitude of location being sent. |
type: String | Address of the location. |
type: String | Name of the location. |
type: String | URL for the website where the user downloaded the location information. |
Inbound messages of type live location are not currently supported.
contacts
When you receive a notification of a user's contact information, the contacts
object provides the contact information details.
This field is different from the contacts
object listed above.
Name | Description |
---|---|
type: Array | Full contact address(es). This field can contain |
type: | Contact's birthday. |
type: Array | Contact email address(es). This field can contain the |
type: Array | Messaging contact information. This field contains the |
type: Array | Full contact name. This field can contain the |
type: Array | Contact organization information. This field can contain the |
type: Array | Contact phone number(s). This field can contain the |
type: Array | Contact URL(s). This field can contain the |
media
When a message with media (image
| document
| audio
| video
| voice
| sticker
) is received, the WhatsApp Business API client will download the media. Once the media is downloaded, a notification is sent to your Webhook. This message contains information that identifies the media object and enables you to find and download the object.
Name | Description |
---|---|
type: String | Optional. Only present if specified. The provided caption for the media. |
type: String | This parameter is deprecated. Absolute filename and location on the media volume. |
type: String | Filename on the sender's device. This will only be present in |
type: String | ID of the media. Can be used to delete the media if stored locally on the client. |
type: Metadata object | Metadata pertaining to |
type: String | Mime type of the media. |
type: String | Checksum. |
system
Notifications of changes to the system are sent in the system
object.
Name | Description |
---|---|
type: String | System event message. |
referral
This object is included in notifications when a user clicks on an ad that clicks to WhatsApp and sends a message to the business. This is how the referral
property works:
referral
property, which provides additional context on the ad that triggered the message. Knowing all this information, the business can appropriately reply to the user message.The referral
property can be included in the following types of message: text, location, contact, image, video, document, voice, and sticker.
You can get the following fields in your referral object:
Name | Description |
---|---|
type: String | Headline used in the ad that generated the message. |
type: String | Body from the ad that generated the message. |
type: String | The type of the ad’s source. Currently, supported values are |
type: String | Facebook ID for an ad or a post. |
type: String | The url that leads to the ad or post. Opening this url takes you to the ad viewed by your user. In some cases, a
|
type: Media object | Optional. The image or video that the user saw and clicked. This object is missing if the |
type: String | Optional. Click ID generated by Meta for Click-To-WhatsApp ads. Example: |
referral media
(video
| image
)Media that was used in the ad. Note that sha256
and mime_type
are not present —mime_type
can be discovered when the media is downloaded.
Name | Description |
---|---|
type: String | ID of the media. This field can be used to delete the media, if stored locally on the client. |
interactive
An interactive
object is found in webhooks related to interactive messages, including List Messages and Reply Button. This object contains the following components:
Name | Description |
---|---|
| Required for Supported values:
|
| Used to notify you when customers are replying to List Messages. Contains the following information about the rows selected by the customer: |
| Used to notify you when customers are replying to Quick Reply Messages. Contains the following information about the button clicked by the customer: |
order
An order object is found in webhooks related to Multi and Single Product Messages. This object contains the following components:
Name | Description |
---|---|
| ID of the catalog that contains the products listed under |
| Array of product items. |
| Text message sent along with the order. |
product_items
A product_item
object is found in webhooks related to Multi-Product Messages. This object contains the following components:
Name | Description |
---|---|
| Unique identifier (in the catalog) of the product. |
| Number of items purchased. |
| Unitary price of the items. |
| Currency of the price. |
statuses
ObjectThe statuses
object keeps you apprised of the status of messages between you and users or groups.
Name | Description (Click the arrow in the left column for supported options.) |
---|---|
type: string | Message ID |
type: string This is duplicated under the message object, as shown in this example. In v2.45 and onwards, it is removed from the | WhatsApp ID of recipient |
type: string | Status of a message. |
type: string | Timestamp of the status message. |
type: string | The type of entity this status object is about. Currently, the only available option is This object is only available for the On-Premises implementation of the API. Cloud API developers will not receive this field. |
type: object | Object containing conversation attributes, including id. See conversation object for more information. WhatsApp defines a conversation as a 24-hour session of messaging between a person and a business. There is no limit on the number of messages that can be exchanged in the fixed 24-hour window. The 24-hour conversation session begins when:
The 24-hour conversation session is different from the 24-hour customer support window. The customer support window is a rolling window that is refreshed when a user-initiated message is delivered to a business. Within the customer support window businesses can send free-form messages. Any business-initiated message sent more than 24 hours after the last customer message must be a template message. |
type: object | Object containing billing attributes, including |
When there are any out-of-band errors that occur in the normal operation of the application, the This type of error can be caused by transient network connectivity errors, invalid credentials, management controllers in unavailable status, etc. See Errors and Status Messages for more information. |
conversation
The conversation
object tracks the attributes of your current conversation. The following fields are specified within the conversation
object:
Name | Description |
---|---|
type: string | Represents the ID of the conversation the given status notification belongs to. |
type: object | Describes the conversation category. See |
type: UNIX timestamp | Timestamp when the current ongoing conversation expires. This field is only present on "message sent" webhooks. See webhooks for more information. |
origin
The origin
object describes conversation category. The following fields are specified within the origin
object:
Name | Description (Click the arrow in the left column for supported options.) |
---|---|
type: string | Indicates conversation category. This can also be referred to as a conversation entry point. |
pricing
The pricing
object includes your billing attributes, but does not include whether a message is part of your account’s free tier. To get free tier information, check the conversation_analytics
field in the Business Management API.
The following fields are specified within the webhooks pricing
object:
Name | Description (Click the arrow in the left column for supported options.) |
---|---|
type: String. “CBP” or “NBP”. | Type of pricing model being used. Current supported value is The Notification-Based Pricing (NBP) model has been deprecated. |
type: boolean | This field was added for a pricing test and is scheduled to be deprecated as early as six months from the On-Premises API v2.37 release. We recommend that you stop using this field before upgrading to the next version. More information on deprecation plans will be provided in the future. Indicates if the given message or conversation is billable. Value varies according to pricing_model.
If you are using NBP (notification-based pricing):
|
type: string | Indicates the conversation pricing category. |
errors
ObjectThe errors
object contains the following parameters:
Name | Description |
---|---|
type: Numeric | Error code. |
type: String | Error title. |
type: String | Optional. Error details provided, if available/applicable. |
type: String | Optional. Location for error detail. |