The following sections contain different object parameters and field descriptions to be used for the Inbound messages.
As shown in the examples contained within this document, notifications of received messages are contained within a messages object. The tables in this section describe the fields in the inbound notifications.
| Name | Description | Type |
|---|---|---|
| contacts | Contacts Object | Array of Contact profile information |
| messages | Messages Object | Array of any type of message objects |
The Contacts Object
The contacts object provides all the information about the contact.
Note: This object only applies to text, contacts, and location messages. It is not currently supported for media messages and not applicable for system messages.
| Name | Description | Type |
|---|---|---|
| profile | As of v2.21.4, contains the sender's profile information. | Profile object |
| wa_id | The WhatsApp ID of the contact | String |
The Profile Object
| Name | Description | Type |
|---|---|---|
| name | Optional. As of v2.21.4, contains the sender's profile name. | String |
The Messages Object
The messages object provides all of the information about the incoming message.
| Name | Description | Type |
|---|---|---|
| context | 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. | String |
| from | WhatsApp ID of the sender | String |
| id | Message ID | String |
| timestamp | Message received timestamp | String |
| type | Message type Supported values are: audio, contacts, document, image, location, text, unknown, video, and voice | String |
| message_objects | Message contents | Array of audio, contacts, document, image, location, system, text, video, and voice objects. See the media object fields for more information. |
| system | Notifications of changes to the system | System Object |
| referral | This object is present when the user clicks on an ad that Clicks to WhatsApp and sends a message to the business | Referral object |
| interactive | This object is present for notifications related to interactive messages | Interactive object |
The Interactive Object
An interactive object is found in Webhooks related to interactive messages, including List Messages and Reply Button.
| Name | Description | Type |
|---|---|---|
| type | Required for list_reply. Supported values:
| String |
| list_reply | Used to notify you when customers are replying to List Messages. | Object Contains the following information about the rows selected by the customer: id, title, and description. |
| button_reply | Used to notify you when customers are replying to Quick Reply Messages. | Object Contains the following information about the button clicked by the customer: id and title. |
The Referral Object
Included in notifications when a user clicks on an ad that clicks to WhatsApp and sends a message to the business. This object has the ad's information.
| Name | Description | Type |
|---|---|---|
| headline | The headline used in the ad that generated the message. | String |
| body | The Body from the ad that generated the message. | String |
| source_type | The type of the ad’s source. Currently, supported values are ad and post. | String |
| source_id | The Facebook ID for an ad or a post. | String |
| source_url | The url that leads to the ad. Opening this url takes you to the ad viewed by your user. | String |
The System Object
Notifications of changes to the system are sent in the system object.
| Name | Description | Type |
|---|---|---|
| body | System event message. | String |
The Context Object
A context object is found in messages where someone has replied to your message. Its purpose is to provide you with a context for the reply.
| Name | Description | Type |
|---|---|---|
| from | WhatsApp ID of the sender of the original message | String |
| id | Message ID of original message | String |
The Text Object
When the notification describes a text message, the text object provides the body of the text message.
| Name | Description | Type |
|---|---|---|
| body | Message text | String |
The Location Object
When you receive a notification of a user's static location, the location object provides the details of the location.
| Name | Description | Type |
|---|---|---|
| latitude | Latitude of location being sent | Number |
| longitude | Longitude of location being sent | Number |
| address | Address of the location | String |
| name | Name of the location | String |
| url | URL for the website where the user downloaded the location information | String |
Inbound messages of type live location are not currently supported.
The Contacts Object
Beginning with v2.21.3, when you receive a notification of a user's contact information, the contacts object provides the contact information details.
Note: This field is different from the contacts object listed above.
| Name | Description | Type |
|---|---|---|
| addresses | Full contact address(es). Each address can contain street, city, state, zip, country, country_code, and type fields. | Array |
| birthday | Contact's birthday | YYYY-MMDD formatted string |
| contact_image | Bas64-encoded contact image in JPEG format | Base64-encoded image |
| emails | Contact email address(es). Each emails object can contains email and type fields. | Array |
| ims | Messaging contact information. Each ims object contains service and user_id fields. | Array |
| name | Full contact name. Each name object can contain first_name, middle_name, last_name, formatted_name, name-prefix, and name_suffix fields. | Array |
| org | Contact organization information. Each org object can contain company, department, and title fields. | Array |
| phones | Contact phone number(s). Each phones object can contain phone, wa_id, and type fields. | Array |
| urls | Contact URL(s). Each urls object can contain url and type fields. | Array |
The Media (image | document | audio | video | voice | sticker) Objects
When a message with media 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 |
|---|---|---|
| caption | Optional (Only present if specified) | String |
| file (This parameter is deprecated) | Absolute filename and location on media volume | String |
| filename | Filename on the sender's device This will only be present in audio and document media messages | String |
| id | ID of the media can be used to delete the media if stored locally on the client | String |
| metadata | Metadata pertaining to sticker media | Metadata object |
| mime_type | Mime type of the media | String |
| sha256 | Checksum | String |
The Order Object
An order object is found in webhooks related to Multi and Single Product Messages. This object contains the following components:
| Name | Description |
|---|---|
| catalog_id | ID of the catalog that contains the products listed under product_items section. |
| product_items | Array of product items. |
| text | Text message sent along with the order. |
The product_items Object
A product_item object is found in webhooks related to Multi-Product Messages. This object contains the following components:
| Name | Description |
|---|---|
| product_retailer_id | Unique identifier (in the catalog) of the product. |
| quantity | Number of items purchased. |
| item_price | Unitary price of the items. |
| currency | Currency of the price. |