This document describes the several types of inbound notifications that may be delivered to the Webhook URL you set in the application settings.
Webhook 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: 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 |
contacts
ObjectThe 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
ObjectThis object contains the sender's profile information.
Name | Description |
---|---|
type: String | Optional. Contains the sender's profile name. |
messages
ObjectThe 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. |
type: Identity Object | Optional. This object will only be included when the |
type: String | Message received timestamp. |
type: String | Message type. |
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. |
context
ObjectA context
object is found in messages where someone has replied to one of your messages. Its purpose is to provide you with a context for the reply.
Name | Description |
---|---|
type: String | WhatsApp ID of the sender of the original message. |
type: String | Message ID of original message. |
identity
ObjectThe 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
ObjectWhen the notification describes a text message, the text
object provides the body of the text message.
Name | Description |
---|---|
type: String | Message text. |
location
ObjectWhen 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
ObjectWhen 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
(image
| document
| audio
| video
| voice
| sticker
) ObjectsWhen 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: 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
ObjectNotifications of changes to the system are sent in the system
object.
Name | Description |
---|---|
type: String | System event message. |
referral
PropertyStarting with version 2.33 of the WhatsApp Business API, inbound message notifications may contain an additional property called referral
. This section is included in notifications when a user clicks on an ad that clicks to WhatsApp and sends a message to the business. You need to be added to an allowlist to have access to the referral
property —please contact your WhatsApp Partner Manager.
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 contain the following types of message:
The following is an example of an inbound image message notification containing referral
. In the example, the user clicked on an ad that contained a video:
{ "messages":[{ "from":"12345678", "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf", "image":{ "id":"b1c68f38-8734-4ad3-b4a1-ef0c10d683", "mime_type":"image/jpeg", "sha256":"29ed500fa64eb55fc19dc4124acb300e5dcca0f822a301ae99944db" "caption": "Check out my product!", }, "timestamp":"1521497954", "type":"image", "referral" : { "headline": "Our new product", "body" : "This is a great product", "source_type": "<SOURCE_TYPE>", "source_id": "<SOURCE_ID>", "source_url": "<SOURCE_URL>", //for the moment, this will always be a Facebook owned domain "video": { "id": "e144be57-12b1-4035-a520-703fcc87ef45", } } }] }
referral
ObjectIncluded 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: 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. Opening this url takes you to the ad viewed by your user. |
type: Media object | Optional. The image or video that the user saw and clicked. This object is missing if the |
referral media
(video
| image
) ObjectsMedia 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. |
You will receive a notification when your business receives a message. The messages
object section below covers all the information you may receive about an incoming message.
This section shows examples of text, location, contacts, forwarded and unknown messages.
The following is an example of a text message received from a customer. See the text
object section below for more information.
{ "contacts": [ { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" } ], "messages":[{ "from": "16315551234", "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf", "timestamp": "1518694235", "text": { "body": "Hello this is an answer" }, "type": "text" }] }
The following is an example of a message received from a customer specifying their static location. See the location
object section below for more information.
{ "contacts": [ { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" } ], "messages":[{ "from":"16315551234", "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf", "location":{ "address":"Main Street Beach, Santa Cruz, CA", "latitude":38.9806263495, "longitude":-131.9428612257, "name":"Main Street Beach", "url":"https://foursquare.com/v/4d7031d35b5df7744"}, "timestamp":"1521497875", "type":"location" }] }
The following is an example of a message received from a customer specifying their contact information. See the contacts
object section below for more information.
{ "contacts": [ { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" } ], "messages": [ { "contacts": [ { "addresses": [ { "city": "Menlo Park", "country": "United States", "country_code": "us", "state": "CA", "street": "1 Hacker Way", "type": "WORK", "zip": "94025" } ], "birthday": "2012-08-18", "emails": [ { "email": "kfish@fb.com", "type": "WORK" } ], "ims": [ { "service": "AIM", "user_id": "kfish" } ], "name": { "first_name": "Kerry", "formatted_name": "Kerry Fisher", "last_name": "Fisher" }, "org": { "company": "Facebook" }, "phones": [ { "phone": "+1 (940) 555-1234", "type": "CELL" }, { "phone": "+1 (650) 555-1234", "type": "WORK", "wa_id": "16505551234" } ], "urls": [ { "url": "https://www.facebook.com", "type": "WORK" } ] } ], "from": "16505551234", "id": "ABGGFlA4dSRvAgo6C4Z53hMh1ugR", "timestamp": "1537248012", "type": "contacts" } ] }
Beginning with v2.29.1
it is possible to see if a message you received has been forwarded or is frequently forwarded.
{ "contacts": [{ "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }], "messages": [{ "context": { "forwarded": true }, "from": "16315558011", "id": "ABGGFmkiWVVPAgo-sOGh7pv13wVJ", "text": { "body": "Party at Dotty's tonight!" }, "timestamp": "1593068329", "type": "text" }] }
{ "contacts": [{ "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }], "messages": [{ "context": { "frequently_forwarded": true }, "from": "16315558011", "id": "ABGGFmkiWVVPAgo-sBTHfS3swNIl", "timestamp": "1593068225", "type": "video", "video": { "id": "e144be57-12b1-4035-a520-703fcc87ef45", "mime_type": "video/mp4", "sha256": "02c4e68a4f0d6af5ec6ef02120e20d15f520a4dd473b535abec1aab175c4e8b9" } }] }
It is possible to receive an unknown
callback notification. The following is an example of an unsupported message type received from a customer.
{ "contacts": [{ "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }], "messages": [{ "errors": [{ "code": 501, "details": "Message type is not currently supported", "title": "Unknown message type" }], "from": "16315551234", "id": "ABGGFRBzFymPAgo6N9KKs7HsN6eB", "timestamp": "1531933468", "type": "unknown" }] }
If the show_security_notifications
parameter is set to true
in the application settings, all inbound message notifications will include the following information about the user's identity contained inside the identity
object.
{ "contacts": [{ "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }], "messages": [{ "from": "16315553601", "id": "ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "identity": { "acknowledged": true, "created_timestamp": 1602532300000, "hash": "Sjvjlx8G6Z0=" }, "text": { "body": "Hi from new number 3601" }, "timestamp": "1602532300", "type": "text" }] }
{ "contacts": [ { "profile": { "name": "Kerry Fisher" }, "wa_id": "16505551234" } ], "messages": [ { "button": { "payload": "No-Button-Payload", "text": "No" }, "context": { "from": "16315558007", "id": "gBGGFmkiWVVPAgkgQkwi7IORac0" }, "from": "16505551234", "id": "ABGGFmkiWVVPAgo-sKD87hgxPHdF", "timestamp": "1591210827", "type": "button" } ] # If there are any errors, an errors field (array) will be present "errors": [ { ... } ] }
When you receive a message with media, the WhatsApp Business API client will download the media. A notification is sent to your Webhook once the media is downloaded. This notification contains information that identifies the media object and enables you to find and retrieve the object. Use the Media endpoint with the media's id
to retrieve the media.
This section shows examples of messages that are received with media.
The following is an example inbound message that contains an image. See the media
object section below to learn more about the different media types.
{ "messages": [{ "from": "16315551234", "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf", "image": { "file": "/usr/local/wamedia/shared/b1cf38-8734-4ad3-b4a1-ef0c10d0d683", "id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683", "mime_type": "image/jpeg", "sha256": "29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db", "caption": "Check out my new phone!" }, "timestamp": "1521497954", "type": "image" }] }
The caption
field is optional for media messages. It is only included if the user has set a caption.
The following is an example inbound message that contains a document. See the media
object section below to learn more about the different media types.
{ "messages": [{ "from": "16315551234", "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf", "timestamp": "1522189546", "type": "document", "document": { "caption": "80skaraokesonglistartist", "file": "/usr/local/wamedia/shared/fc233119-733f-49c-bcbd-b2f68f798e33", "id": "fc233119-733f-49c-bcbd-b2f68f798e33", "mime_type": "application/pdf", "sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e" } }]
The following is an example inbound message that contains a voice message. See the media
object section below to learn more about the different media types.
{ "messages":[{ "from": "16315551234", "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf", "timestamp": "1521827831", "type": "voice", "voice": { "file": "/usr/local/wamedia/shared/463e/b7ec/ff4e4d9bb1101879cbd411b2", "id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2", "mime_type": "audio/ogg; codecs=opus", "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"} }] }
The following is an example inbound message that contains a sticker. See the media
object section below to learn more about the different media types.
{ "messages":[{ "from": "16315551234", "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf", "timestamp": "1521827831", "type": "sticker", "sticker": { "id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683", "metadata": { "sticker-pack-id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2", "sticker-pack-name" : "Happy New Year", "sticker-pack-publisher" : "Kerry Fisher", "emojis": ["🐥", "😃"], "ios-app-store-link" : "https://apps.apple.com/app/id3133333", "android-app-store-link" : "https://play.google.com/store/apps/details?id=com.example", "is-first-party-sticker" : 0 | 1 # integer }, "mime_type": "image/webp", "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710" } }] }
Users can respond to a specific message in WhatsApp. For the business to understand the context of a message reply, we include the context
object. This context
object provides the id
of the message to which the customer replied and the WhatsApp ID of the sender of the original message.
Replying to Messages contains more information.
The following is an example of an inbound message that is a reply to a message that you sent. See the context
object section below for more information.
{ "contacts": [ { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" } ], "messages":[{ "context":{ "from":"16315558011", "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf" }, "from":"16315551234", "id":"gBGGFlA5FpafAgkOuJbRq54qwbM", "text":{"body":"Yes, count me in!"}, "timestamp":"1521499915", "type":"text" }] }
The text
field is optional for media messages. If it exists, the text
value is the caption of the sent media or the body of the response, if the response is a text message.
System messages are generated by the system when some event happens. See the system
object section below for more information.
If the notify_user_change_number
parameter is set to true
in the application settings you will receive inbound system messages when a user changes their phone number.
{ "messages": [ { "from": "16315558889", "id": "ABGGFjFVWIifAzNzeXMtMTYzMTU1NTg4ODlAcy53aGF0c2FwcC5uZXQtMTU3NDA4MDEwMjIxMy1jaGFuZ2U", "system": { "body": "User A changed from +1 (631) 555-8889 to +1 (631) 555-8890", "new_wa_id": "16315558890", "type": "user_changed_number" }, "timestamp": "1574080102", "type": "system" } ] }
If the show_security_notifications
parameter is set to true
in the application settings you will receive inbound system messages when a user (in conversation with you) has potentially changed on WhatsApp.
Until this notification is acknowledged using the identity
endpoint, all outgoing messages to this user will be blocked. Incoming messages will continue to be received as expected.
{ "messages": [ { "from": "16315553601", "id": "ABGGFjFVU2AfAzVzeXMtMTYzMTU1NTM2MDFAcy53aGF0c2FwcC5uZXQtMTYwMjUzNTM1NjMzMi1pZGVudGl0eQ", "system": { "body": "Test security code change", "identity": "Rc/eg9Rl0JA=", "type": "user_identity_changed", "user": "16315553601" }, "timestamp": "1602535356", "type": "system" } ] }
System Message Type | Description |
---|---|
| User's phone number changed |
| User has potentially changed on WhatsApp |
When you send a message that mentions a particular WhatsApp ID directly and someone replies to that message, you will see the mentioned ID in the context
object and in the mentions
array. Because more than one phone number can be mentioned, the mentions
field is an array of phone numbers, even if only one phone number is mentioned.
The following is an example of a customer replying to a message that contained mentions. The context
object contains the numbers mentioned in the original message. The reply in the text
object mentions the same numbers again.
{ "messages": [{ "context": { "from": "16315555544", "id": "gBGGFlA5FpafAgkOuJbRq54qwbM", "mentions": [ "16315551000", "16315551099" ] }, "from": "16315551234 ", "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf", "timestamp": "1504902988", "text": { "body": "@16315551000 and @16315551099 are mentioned" }, "type": "text" }] }
You can use the messages
node to change the status of incoming messages to read
.
pass_through
to false
in the application settings.When pass_through
is set to true
, messages are removed from the local database after they are delivered to or read by the recipient. But, when it is set to false
, incoming messages are saved in local database for 7 days, after which they are deleted if db_garbagecollector_enable
is set to true
.
We recommend marking incoming messages as read within 7 days of receipt.
The message_id
used in this API call is the id
provided in the inbound notification.
PUT /v1/messages/message-id { "status": "read" }
Name | Description |
---|---|
| Required. Updating |
null # or {}