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.
When you receive an inboud message, a notification is sent to the Webhook URL you set in the application settings. This document goes over the inbound messages you can receive and provides examples.
Received messages notifications can contain the following objects:
When you receive a message with media, the WhatsApp Business API client downloads 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.
{ "contacts": [{ "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }], "messages":[{ "from": "16315551234", "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf", "timestamp": "1518694235", "text": { "body": "Hello this is an answer" }, "type": "text" }] }
{ "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" }] }
{ "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": "Meta", "department": "WhatsApp" }, "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" }] }
The contact_image
setting is empty if the consumer client is using an IPhone.
Message containing an image:
{ "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!", "status": "downloaded" }, "timestamp": "1521497954", "type": "image" }] }
Starting with 2.49.1
version media message webhooks contain the state and id of the received media.
State | Description |
---|---|
| Media was succesfully download |
| Media was not downloaded, but the download may be retried using the retry endpoint |
| Media may not be downloaded |
The caption
field is optional for media messages. It is only included if the user has set a caption.
Message containing a document:
{ "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", "status": "downloaded" } }] }
Voice message:
{ "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", "status": "downloaded" } }] }
Message containing a sticker:
{ "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" } }] }
{ "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", "ctwa_clid": "<CTWA_CLID>", } } }] }
See more information about the referral
property.
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" }] }
You can see if a message you received has been forwarded or is frequently forwarded. This is a notification for a forwarded message:
{ "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" }] }
This is a notification for a frequently forwarded message:
{ "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" } }] }
If the show_security_notifications
parameter is set to true
in the application settings, all inbound message notifications 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": [ { ... } ] }
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, the WhatsApp ID of the sender of the original message and IDs for any products the customer may be referring to.
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.
{ "messages": [ { "context": { "from": "sender_wa_id_of_context_message", "group_id": "group_id_of_context_message", "id": "message_id_of_context_message", "mentions": [ "wa_id1", "wa_id2" ] }, "from": "sender_wa_id", "group_id": "group_id", "id": "message_id", "timestamp": "message_timestamp", "type": "interactive", "interactive": { "type": "list_reply", "list_reply": { "title": "row-title-content-here", "id": "unique-row-identifier-here", "description": "row-description-content-here" } } }
{ "messages": [ { "context": { "from": "sender_wa_id_of_context_message", "group_id": "group_id_of_context_message", "id": "message_id_of_context_message", "mentions": [ "wa_id1", "wa_id2" ] }, "from": "sender_wa_id", "group_id": "group_id", "id": "message_id", "timestamp": "message_timestamp", "type": "interactive", "interactive": { "type": "button_reply", "button_reply": { "id": "unique-button-identifier", "title": "button-text" } } # end interactive node } # end message item ] # end messages array }
{ "contacts": [ { "profile": { "name": "customer-name" }, "wa_id": "customer-whatsapp-ID" } ], "messages": [ { "from": "customer-whatsapp-ID", "id": "message-ID", "text": { "body": "Can I get this in another color?" }, "context": { "referred_product": { "catalog_id": "catalog-ID", "product_retailer_id": "product-ID" } }, "timestamp": "message-received-timestamp", "type": "text" } ] }
{ "messages": [ { "from": "customer-whatsapp-id", "group_id": "group-id", "id": "message-ID", "timestamp": "message-timestamp", "type": "order" "order": { "catalog_id": "catalog_id", "product_items": [ { "product_retailer_id":"product-ID", "quantity":"number-of-items", "item_price":"unitary-price-of-item", "currency":"price-currency" }, ... ], "text":"text-message-sent-along-with-the-order" } } }
System messages are generated by the system when some event happens.
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" }] }