Parameter/Field Descriptions for 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.

  <th style={{ textAlign: "left" }}>
    Description
  </th>

  <th style={{ textAlign: "left" }}>
    Type
  </th>
</tr>

  <td style={{ textAlign: "left" }}>
    Contacts Object
  </td>

  <td style={{ textAlign: "left" }}>
    Array of Contact profile information
  </td>
</tr>

<tr>
  <td style={{ textAlign: "left" }}>
    messages
  </td>

  <td style={{ textAlign: "left" }}>
    Messages Object
  </td>

  <td style={{ textAlign: "left" }}>
    Array of any type of message objects
  </td>
</tr>

Name
contacts

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.

  <th>
    Description
  </th>

  <th>
    Type
  </th>
</tr>

  <td>
    As of v2.21.4, contains the sender's profile information.
  </td>

  <td>
    Profile object
  </td>
</tr>

<tr>
  <td>
    wa\_id
  </td>

  <td>
    The WhatsApp ID of the contact
  </td>

  <td>
    String
  </td>
</tr>

Name
profile

The Profile Object

  <th>
    Description
  </th>

  <th>
    Type
  </th>
</tr>

  <td>
    Optional. As of v2.21.4, contains the sender's profile name.
  </td>

  <td>
    String
  </td>
</tr>

Name
name

The Messages Object

The messages object provides all of the information about the incoming message.

  <th>
    Description
  </th>

  <th>
    Type
  </th>
</tr>

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

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    from
  </td>

  <td>
    WhatsApp ID of the sender
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    id
  </td>

  <td>
    Message ID
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    timestamp
  </td>

  <td>
    Message received timestamp
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    type
  </td>

  <td>
    Message type

    Supported values are: *audio, contacts, document, image, location, text, unknown, video, and voice*
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    message\_objects
  </td>

  <td>
    Message contents
  </td>

  <td>
    Array of audio, contacts, document, image, location, system, text, video, and voice objects.\
    type: Message type objects that provide more information about the received message.

    See the media object fields for more information.
  </td>
</tr>

<tr>
  <td>
    system
  </td>

  <td>
    Notifications of changes to the system
  </td>

  <td>
    System Object
  </td>
</tr>

<tr>
  <td>
    referral
  </td>

  <td>
    This object is present when the user clicks on an ad that Clicks to WhatsApp and sends a message to the business
  </td>

  <td>
    Referral object
  </td>
</tr>

<tr>
  <td>
    interactive
  </td>

  <td>
    This object is present for notifications related to interactive messages
  </td>

  <td>
    Interactive object
  </td>
</tr>

Name
context

The Interactive Object

An interactive object is found in Webhooks related to interactive messages, including List Messages and Reply Button.

  <th>
    Description
  </th>

  <th>
    Type
  </th>
</tr>

  <td>
    Required for **list\_reply**.

    Supported values:

    * list\_reply for List Messages
    * button\_reply for Reply Button Messages
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    list\_reply
  </td>

  <td>
    Used to notify you when customers are replying to List Messages.
  </td>

  <td>
    Object

    Contains the following information about the rows selected by the customer: *id, title, and description*.
  </td>
</tr>

<tr>
  <td>
    button\_reply
  </td>

  <td>
    Used to notify you when customers are replying to Quick Reply Messages.
  </td>

  <td>
    Object

    Contains the following information about the button clicked by the customer: *id and title*.
  </td>
</tr>

Name
type

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.

  <th>
    Description
  </th>

  <th>
    Type
  </th>
</tr>

  <td>
    The headline used in the ad that generated the message.
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    body
  </td>

  <td>
    The Body from the ad that generated the message.
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    source\_type
  </td>

  <td>
    The type of the ad’s source. Currently, supported values are ad and post.
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    source\_id
  </td>

  <td>
    The Facebook ID for an ad or a post.
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    source\_url
  </td>

  <td>
    The url that leads to the ad. Opening this url takes you to the ad viewed by your user.
  </td>

  <td>
    String
  </td>
</tr>

Name
headline

The System Object

Notifications of changes to the system are sent in the system object.

  <th>
    Description
  </th>

  <th>
    Type
  </th>
</tr>

  <td>
    System event message.
  </td>

  <td>
    String
  </td>
</tr>

Name
body

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.

  <th>
    Description
  </th>

  <th>
    Type
  </th>
</tr>

  <td>
    WhatsApp ID of the sender of the original message
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    id
  </td>

  <td>
    Message ID of original message
  </td>

  <td>
    String
  </td>
</tr>

Name
from

The Text Object

When the notification describes a text message, the text object provides the body of the text message.

  <th>
    Description
  </th>

  <th>
    Type
  </th>
</tr>

  <td>
    Message text
  </td>

  <td>
    String
  </td>
</tr>

Name
body

The Location Object

When you receive a notification of a user's static location, the location object provides the details of the location.

  <th>
    Description
  </th>

  <th>
    Type
  </th>
</tr>

  <td>
    Latitude of location being sent
  </td>

  <td>
    Number
  </td>
</tr>

<tr>
  <td>
    longitude
  </td>

  <td>
    Longitude of location being sent
  </td>

  <td>
    Number
  </td>
</tr>

<tr>
  <td>
    address
  </td>

  <td>
    Address of the location
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    name
  </td>

  <td>
    Name of the location
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    url
  </td>

  <td>
    URL for the website where the user downloaded the location information
  </td>

  <td>
    String
  </td>
</tr>

Name
latitude

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

  <th>
    Description
  </th>

  <th>
    Type
  </th>
</tr>

  <td>
    Full contact address(es). Each address can contain street, city, state, zip, country, country\_code, and type fields.
  </td>

  <td>
    Array
  </td>
</tr>

<tr>
  <td>
    birthday
  </td>

  <td>
    Contact's birthday
  </td>

  <td>
    YYYY-MMDD formatted string
  </td>
</tr>

<tr>
  <td>
    contact\_image
  </td>

  <td>
    Bas64-encoded contact image in JPEG format
  </td>

  <td>
    Base64-encoded image
  </td>
</tr>

<tr>
  <td>
    emails
  </td>

  <td>
    Contact email address(es). Each emails object can contains email and type fields.
  </td>

  <td>
    Array
  </td>
</tr>

<tr>
  <td>
    ims
  </td>

  <td>
    Messaging contact information. Each ims object contains service and user\_id fields.
  </td>

  <td>
    Array
  </td>
</tr>

<tr>
  <td>
    name
  </td>

  <td>
    Full contact name. Each name object can contain first\_name, middle\_name, last\_name, formatted\_name, name-prefix, and name\_suffix fields.
  </td>

  <td>
    Array
  </td>
</tr>

<tr>
  <td>
    org
  </td>

  <td>
    Contact organization information. Each org object can contain company, department, and title fields.
  </td>

  <td>
    Array
  </td>
</tr>

<tr>
  <td>
    phones
  </td>

  <td>
    Contact phone number(s). Each phones object can contain phone, wa\_id, and type fields.
  </td>

  <td>
    Array
  </td>
</tr>

<tr>
  <td>
    urls
  </td>

  <td>
    Contact URL(s). Each urls object can contain url and type fields.
  </td>

  <td>
    Array
  </td>
</tr>

Name
addresses

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.

  <th>
    Description
  </th>

  <th>
    Type
  </th>
</tr>

  <td>
    Optional (Only present if specified)
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    file *(This parameter is deprecated)* 
  </td>

  <td>
    Absolute filename and location on media volume
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    filename
  </td>

  <td>
    Filename on the sender's device This will only be present in audio and document media messages
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    id
  </td>

  <td>
    ID of the media can be used to delete the media if stored locally on the client
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    metadata
  </td>

  <td>
    Metadata pertaining to sticker media
  </td>

  <td>
    Metadata object
  </td>
</tr>

<tr>
  <td>
    mime\_type
  </td>

  <td>
    Mime type of the media
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    sha256
  </td>

  <td>
    Checksum
  </td>

  <td>
    String
  </td>
</tr>

Name
caption

The Order Object

An order object is found in webhooks related to Multi and Single Product Messages. This object contains the following components:

  <th>
    Description
  </th>
</tr>

  <td>
    ID of the catalog that contains the products listed under **product\_items** section.
  </td>
</tr>

<tr>
  <td>
    product\_items
  </td>

  <td>
    Array of product items.
  </td>
</tr>

<tr>
  <td>
    text
  </td>

  <td>
    Text message sent along with the order.
  </td>
</tr>

Name
catalog\_id

The product_items Object

A product_item object is found in webhooks related to Multi-Product Messages. This object contains the following components:

  <th>
    Description
  </th>
</tr>

  <td>
    Unique identifier (in the catalog) of the product.
  </td>
</tr>

<tr>
  <td>
    quantity
  </td>

  <td>
    Number of items purchased.
  </td>
</tr>

<tr>
  <td>
    item\_price
  </td>

  <td>
    Unitary price of the items.
  </td>
</tr>

<tr>
  <td>
    currency
  </td>

  <td>
    Currency of the price.
  </td>
</tr>

Name
product\_retailer\_id

The Contacts Object

The Profile Object

The Messages Object

The Interactive Object

The Referral Object

The System Object

The Context Object

The Text Object

The Location Object

❗️Inbound messages of type live location are not currently supported.

The Contacts Object

The Media (image | document | audio | video | voice | sticker) Objects

The Order Object

The product_items Object

❗️
Inbound messages of type live location are not currently supported.