On-Premises API

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.

Components

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:

NameObject contents

messages

Webhook notifications of received messages are contained within a messages object.

statuses

The statuses object keeps you apprised of the status of messages between you and users or groups.

The messages Object

The messages object contains the following components:

NameDescription

contacts

type: Array of contact profile information

Provides all the information about the contact —see contacts object. 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.


Inside contacts, the profile object is nested.

messages

type: Array of any type of message objects

Provides all of the information about the incoming message —see messages object.


Inside messages, the following objects are nested: context, identity, media, referral, text, location, contacts, system, and interactive.

recipient_id

type: string

WhatsApp ID of recipient

errors

When there are any out-of-band errors that occur in the normal operation of the application, the errors array provides a description of the error.


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.

NameDescription

profile

type: Profile object

Contains the sender's profile information.

wa_id

type: String

The WhatsApp ID of the contact.

profile

This object contains the sender's profile information.

NameDescription

name

type: String

Optional.

Contains the sender's profile name.

messages

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

NameDescription

context

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 context object for more information.

from

type: String

WhatsApp ID of the sender.

id

type: String

Message ID.


This ID can be used to mark a message as read.

identity

type: Identity Object

Optional.
Contains information about the user identity used to decrypt the incoming message. See identity object.


This object will only be included when the show_security_notifications parameter is set to true in the application settings.

timestamp

type: String

Message received timestamp.

type

type: String

Message type.
Supported values are: audio, contacts, document, image, location, text, unknown, video, voice, ephemeral*.


*If a user sends a disappearing message to the business, the businesses gets notified via a webhooks notification with type set to "ephemeral". Businesses will not be able to see the message's content.

audio, contacts, document, image, location, system, text, video, and voice objects

type: Message type objects that provide more information about the received message.

Message contents. See the media object fields for more information.

referral

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.

system

type: System Object

Notifications of changes to the system.

interactive

type: Interactive Object

This object is present for notifications related to interactive messages. See interactive object for more information.

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.

NameDescription

from

type: String

Optional. Will not be present if the user only interacts with the message.

WhatsApp ID of the sender of the original message.

id

type: String

Optional. Will not be present if the user only interacts with the message.

Message ID of original message.

referred_product

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.

NameDescription

catalog_id

ID for the catalog the item belongs to.

product_retailer_id

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.

NameDescription

acknowledged

type: String

State of acknowledgment for latest user_identity_changed system notification.

created_timestamp

type: Int

Timestamp of when the WhatsApp Business API client detected the user potentially changed.

hash

type: String

Identifier for the latest user_identity_changed system notification.

text

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

NameDescription

body

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.

NameDescription

latitude

type: Number

Latitude of location being sent.

longitude

type: Number

Longitude of location being sent.

address

type: String

Address of the location.

name

type: String

Name of the location.

url

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.

NameDescription

addresses

type: Array

Full contact address(es). This field can contain street, city, state, zip, country, country_code, and type fields.

birthday

type: YYYY-MM-DD formatted string

Contact's birthday.

emails

type: Array

Contact email address(es). This field can contain the email and type parameters.

ims

type: Array

Messaging contact information. This field contains the service and user_id parameters.

name

type: Array

Full contact name. This field can contain the first_name, middle_name, last_name, formatted_name, name-prefix, and name_suffix parameters.

org

type: Array

Contact organization information. This field can contain the company, department, and title parameters.

phones

type: Array

Contact phone number(s). This field can contain the phone, wa_id, and type parameters.

urls

type: Array

Contact URL(s). This field can contain the url and type parameters.

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.

NameDescription

caption

type: String

Optional. Only present if specified.

The provided caption for the media.

file

type: String

This parameter is deprecated.

Absolute filename and location on the media volume.

filename

type: String

Filename on the sender's device. This will only be present in document media messages.

id

type: String

ID of the media. Can be used to delete the media if stored locally on the client.

metadata

type: Metadata object

Metadata pertaining to sticker media.

mime_type

type: String

Mime type of the media.

sha256

type: String

Checksum.

system

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

NameDescription

body

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:

  1. A user clicks on an ad with the Click to WhatsApp call-to-action.
  2. User is redirected to WhatsApp and sends a message to the advertising business.
  3. User sends a message to the business. Be aware that users may elect to remove their referral data.
  4. The advertising business gets an inbound message notification including the 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:

NameDescription

headline

type: String

Headline used in the ad that generated the message.

body

type: String

Body from the ad that generated the message.

source_type

type: String

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

source_id

type: String

Facebook ID for an ad or a post.

source_url

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 referral object may contain only the source_url field. This is expected and happens due to:

  • A user sending the message before the context for the ad or post has been rendered on the user’s app.
  • An error or mismatch when the user's client tries to look for an ad or post’s context.

image and video

type: Media object

Optional.

The image or video that the user saw and clicked. This object is missing if the skip_referral_media_download application setting is set to true. See application settings for more details.

ctwa_clid

type: String

Optional.

Click ID generated by Meta for Click-To-WhatsApp ads.

Example:
"ARCyp87FhJaKKiQqAP52kFsRe0AmmbZ1NN8jJ2fvNHyBqMwDHKQBjCJu1bN6W4G2ueq3GmA_5tN8zk4dnhrlG_18delJc8R8Ldc9vGE_nk9AgMDz"

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.

NameDescription

id

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:

NameDescription

type

Required for list_reply.

Supported values:

  • list_reply for List Messages
  • button_reply for Reply Button Messages

list_reply

Used to notify you when customers are replying to List Messages.


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.


Contains the following information about the button clicked by the customer: id and title.

order

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

NameDescription

catalog_id

ID of the catalog that contains the products listed under product_items sections.

product_items

Array of product items.

text

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:

NameDescription

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.

The statuses Object

The statuses object keeps you apprised of the status of messages between you and users or groups.

NameDescription (Click the arrow in the left column for supported options.)

id

type: string

Message ID

recipient_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 status object to avoid duplication. Please update your integration to use recipient_id under the message object.

WhatsApp ID of recipient

status

type: string

Status of a message.

Supported Values

  • deleted
  • delivered
  • failed
  • read
  • sent
  • warning

warning indicates an item in a catalog is not available or does not exist.

This status is only available to developers on the On-Premises API. It is not yet available to developers on Cloud API.

timestamp

type: string

Timestamp of the status message.

type

type: string

The type of entity this status object is about. Currently, the only available option is "message".


This object is only available for the On-Premises implementation of the API. Cloud API developers will not receive this field.

conversation

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:

  • A business-initiated message is delivered to a user
  • A business’ reply to a user message is delivered

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.

pricing

type: object

Object containing billing attributes, including pricing_model, billable flag, and category. See pricing object for more information.

errors

When there are any out-of-band errors that occur in the normal operation of the application, the errors array provides a description of the error.


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:

NameDescription

id

type: string

Represents the ID of the conversation the given status notification belongs to.

origin

type: object

Describes the conversation category. See origin object for more information.

expiration_timestamp

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:

NameDescription (Click the arrow in the left column for supported options.)

type

type: string

Indicates conversation category. This can also be referred to as a conversation entry point.

Available Options

  • authentication: indicates that the conversation was opened by a business sending a template categorized as AUTHENTICATION message to a customer. This applies any time it has been more than 24 hours since the last customer message.
  • marketing: indicates that the conversation was opened by a business sending a template categorized as MARKETING message to a customer. This applies any time it has been more than 24 hours since the last customer message.
  • utility: indicates that the conversation was opened by a business sending a template categorized as UTILITY message to a customer. This applies any time it has been more than 24 hours since the last customer message.
  • service: indicates that the conversation started by a business replying to a customer within a customer service window.
  • referral_conversion: indicates a free entry point conversation.

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:

NameDescription (Click the arrow in the left column for supported options.)

pricing_model

type: String. “CBP” or “NBP”.

Type of pricing model being used. Current supported value is "CBP".


The Notification-Based Pricing (NBP) model has been deprecated.

billable

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.


  • This flag is set to false if the conversation was initiated from free entry points. Conversations initiated from free entry points are not billable.
  • For all other conversations, it’s set to true.
  • This is also set to true for conversations inside your free tier limit. You will not be charged for these conversations, but they are considered billable and will be reflected on your invoice.

If you are using NBP (notification-based pricing):

  • This flag is false for service conversations.
  • This flag is set to true for authentication, marketing, and utility conversations.

category

type: string

Indicates the conversation pricing category.

Supported Values

  • business_initiated: indicates that the conversation started by a business sending the first message to a user. This applies any time it has been more than 24 hours since the last user message.
  • user_initiated: indicates that the conversation started by a business replying to a user message. This applies only when the business reply is within 24 hours of the last user message.
  • referral_conversion: indicates that the conversation originated from a free entry point. These conversations are always user-initiated.

The errors Object

The errors object contains the following parameters:

NameDescription

code

type: Numeric

Error code.

title

type: String

Error title.

details

type: String

Optional. Error details provided, if available/applicable.

href

type: String

Optional. Location for error detail.