Messaging Webhooks (associated with Messaging API)
After the webhook is set for the number , it will receive notifications about messaging events. These events are grouped and can be used for:
Inbound Message Notifications: Use it to get a notification when a customer performs an action, such as:
Sends a text message to the business
Sends an image, video, audio, document, or sticker to the business
Sends contact information to the business
Sends location information to the business
Clicks a reply button set up by the business
Clicks a call-to-actions button on an Ad that Clicks to WhatsApp
Clicks an item on a business' list
Updates their profile information such as their phone number
Asks for information about a specific product
Orders products being sold by the business
Message Status Notifications : Use it to monitor the status of sent messages.
If a webhook event isn't delivered for any reason (e.g., the client is offline) or if the webhook request returns a HTTP status code other than 200, we retry the webhook delivery. We continue retrying delivery with increasing delays up to a certain timeout (typically 24 hours, though this may vary), or until the delivery succeeds.
For Cloud API, the object is always whatsapp_business_account but the field will be indicative of the type of information being sent.
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : PHONE_NUMBER ,
"phone_number_id" : PHONE_NUMBER_ID
} ,
"contacts" : [{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : PHONE_NUMBER
}] ,
"messages" : [{
"from" : PHONE_NUMBER ,
"id" : "wamid.ID" ,
"timestamp" : TIMESTAMP ,
"text" : {
"body" : "MESSAGE_BODY"
} ,
"type" : "text"
}]
} ,
"field" : "messages"
}]
}]
} [will be deprecated] For On-premise API, the object will be contacts and messages, errors, or statuses and pricing.
Copy {
"contacts" : [{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : "WHATSAPP_BUSINESS_ACCOUNT_ID"
}] ,
"messages" : [{
"from" : "PHONE_NUMBER" ,
"id" : "wamid.ID" ,
"timestamp" : "TIMESTAMP" ,
"text" : {
"body" : "MESSAGE_BODY"
} ,
"type" : "text"
}]
} Text Messages
See Text Messages.
The following is an example of a text message you received from a customer:
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : PHONE_NUMBER ,
"phone_number_id" : PHONE_NUMBER_ID
} ,
"contacts" : [{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : PHONE_NUMBER
}] ,
"messages" : [{
"from" : PHONE_NUMBER ,
"id" : "wamid.ID" ,
"timestamp" : TIMESTAMP ,
"text" : {
"body" : "MESSAGE_BODY"
} ,
"type" : "text"
}]
} ,
"field" : "messages"
}]
}]
} Reaction Messages
See Reaction Messages .
The following is an example of a reaction message you received from a customer. You will not receive this webbook if the message the customer is reacting to is more than 30 days old.
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : PHONE_NUMBER ,
"phone_number_id" : PHONE_NUMBER_ID
} ,
"contacts" : [{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : PHONE_NUMBER
}] ,
"messages" : [{
"from" : PHONE_NUMBER ,
"id" : "wamid.ID" ,
"timestamp" : TIMESTAMP ,
"reaction" : {
"message_id" : "MESSAGE_ID" ,
"emoji" : "EMOJI"
} ,
"type" : "reaction"
}]
} ,
"field" : "messages"
}]
}]
} Note that for reactions, the timestamp value indicates when the customer sent the reaction, not when the webhook was generated.
Media Messages
See Media Messages .
When a message with media is received, the WhatsApp Business Platform downloads the media. A notification is sent to the Webhook once the media is downloaded.
The Webhook notification contains information that identifies the media object and enables you to find and retrieve the object. Use the media endpoints to retrieve the media .
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : PHONE_NUMBER ,
"phone_number_id" : PHONE_NUMBER_ID
} ,
"contacts" : [{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : "WHATSAPP_ID"
}] ,
"messages" : [{
"from" : PHONE_NUMBER ,
"id" : "wamid.ID" ,
"timestamp" : TIMESTAMP ,
"type" : "image" ,
"image" : {
"caption" : "CAPTION" ,
"mime_type" : "image/jpeg" ,
"sha256" : "IMAGE_HASH" ,
"id" : "ID"
}
}]
} ,
"field" : "messages"
}]
}]
}
When you receive a sticker, you will get the following notification:
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [
{
"id" : "ID" ,
"changes" : [
{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "PHONE_NUMBER" ,
"phone_number_id" : "PHONE_NUMBER_ID"
} ,
"contacts" : [
{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : "ID"
}
] ,
"messages" : [
{
"from" : "SENDER_PHONE_NUMBER" ,
"id" : "wamid.ID" ,
"timestamp" : "TIMESTAMP" ,
"type" : "sticker" ,
"sticker" : {
"mime_type" : "image/webp" ,
"sha256" : "HASH" ,
"id" : "ID"
}
}
]
} ,
"field" : "messages"
}
]
}
]
} Unknown Messages
It's possible to receive an unknown message callback notification. For example, a customer could send you a message that's not supported, such as a disappearing message (in which case Meta notifies the that the message type is not supported).
The following is an example of a message you received from a customer that is not supported.
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "PHONE_NUMBER" ,
"phone_number_id" : "PHONE_NUMBER_ID"
} ,
"contacts" : [{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : "WHATSAPP_ID"
}] ,
"messages" : [{
"from" : "PHONE_NUMBER" ,
"id" : "wamid.ID" ,
"timestamp" : "TIMESTAMP" ,
"errors" : [
{
"code" : 131051 ,
"details" : "Message type is not currently supported" ,
"title" : "Unsupported message type"
}] ,
"type" : "unknown"
}]
}
"field" : "messages"
}] ,
}]
} Location Messages
See Location Messages .
The following is an example of a location message you received from a customer:
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "PHONE_NUMBER" ,
"phone_number_id" : "PHONE_NUMBER_ID"
} ,
"contacts" : [{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : "WHATSAPP_ID"
}] ,
"messages" : [{
"from" : "PHONE_NUMBER" ,
"id" : "wamid.ID" ,
"timestamp" : "TIMESTAMP" ,
"location" : {
"latitude" : LOCATION_LATITUDE ,
"longitude" : LOCATION_LONGITUDE ,
"name" : LOCATION_NAME ,
"address" : LOCATION_ADDRESS ,
}
}]
} ,
"field" : "messages"
}]
}]
} Contacts Messages
See Contacts Messages .
The following is an example of a contact message you received from a customer:
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "PHONE_NUMBER" ,
"phone_number_id" : "PHONE_NUMBER_ID"
} ,
"contacts" : [{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : "WHATSAPP_ID"
}] ,
"messages" : [{
"from" : "PHONE_NUMBER" ,
"id" : "wamid.ID" ,
"timestamp" : "TIMESTAMP" ,
"contacts" : [{
"addresses" : [{
"city" : "CONTACT_CITY" ,
"country" : "CONTACT_COUNTRY" ,
"country_code" : "CONTACT_COUNTRY_CODE" ,
"state" : "CONTACT_STATE" ,
"street" : "CONTACT_STREET" ,
"type" : "HOME or WORK" ,
"zip" : "CONTACT_ZIP"
}] ,
"birthday" : "CONTACT_BIRTHDAY" ,
"emails" : [{
"email" : "CONTACT_EMAIL" ,
"type" : "WORK or HOME"
}] ,
"name" : {
"formatted_name" : "CONTACT_FORMATTED_NAME" ,
"first_name" : "CONTACT_FIRST_NAME" ,
"last_name" : "CONTACT_LAST_NAME" ,
"middle_name" : "CONTACT_MIDDLE_NAME" ,
"suffix" : "CONTACT_SUFFIX" ,
"prefix" : "CONTACT_PREFIX"
} ,
"org" : {
"company" : "CONTACT_ORG_COMPANY" ,
"department" : "CONTACT_ORG_DEPARTMENT" ,
"title" : "CONTACT_ORG_TITLE"
} ,
"phones" : [{
"phone" : "CONTACT_PHONE" ,
"wa_id" : "CONTACT_WA_ID" ,
"type" : "HOME or WORK>"
}] ,
"urls" : [{
"url" : "CONTACT_URL" ,
"type" : "HOME or WORK"
}]
}]
}]
} ,
"field" : "messages"
}]
}]
} Received Callback from a Quick Reply Button
See Interactive Messages.
When your customer clicks on a quick reply button in an interactive message template , a response is sent. Below is an example of the callback format.
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : PHONE_NUMBER ,
"phone_number_id" : PHONE_NUMBER_ID
} ,
"contacts" : [{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : "WHATSAPP_ID"
}] ,
"messages" : [{
"context" : {
"from" : PHONE_NUMBER ,
"id" : "wamid.ID"
} ,
"from" : "16315551234" ,
"id" : "wamid.ID" ,
"timestamp" : TIMESTAMP ,
"type" : "button" ,
"button" : {
"text" : "No" ,
"payload" : "No-Button-Payload"
}
}]
} ,
"field" : "messages"
}]
}]
} Received Answer From List Message
See Interactive Messages.
The following webhook notification is received when a user clicks on an item from a list message you sent:
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [
{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [
{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "PHONE_NUMBER" ,
"phone_number_id" : "PHONE_NUMBER_ID" ,
} ,
"contacts" : [
{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : "PHONE_NUMBER_ID"
}
] ,
"messages" : [
{
"from" : PHONE_NUMBER_ID ,
"id" : "wamid.ID" ,
"timestamp" : TIMESTAMP ,
"interactive" : {
"list_reply" : {
"id" : "list_reply_id" ,
"title" : "list_reply_title" ,
"description" : "list_reply_description"
} ,
"type" : "list_reply"
} ,
"type" : "interactive"
}
]
} ,
"field" : "messages"
}
]
}
]
} Received Answer to Reply Button
See Interactive Messages.
The following webhook notification is received when a user clicks on a reply button you sent:
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [
{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [
{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "PHONE_NUMBER" ,
"phone_number_id" : PHONE_NUMBER_ID ,
} ,
"contacts" : [
{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : "PHONE_NUMBER_ID"
}
] ,
"messages" : [
{
"from" : PHONE_NUMBER_ID ,
"id" : "wamid.ID" ,
"timestamp" : TIMESTAMP ,
"interactive" : {
"button_reply" : {
"id" : "unique-button-identifier-here" ,
"title" : "button-text" ,
} ,
"type" : "button_reply"
} ,
"type" : "interactive"
}
]
} ,
"field" : "messages"
}
]
}
]
} Received Message Triggered by Click to WhatsApp Ads
You get the following webhook when a conversation is started after a user clicks an ad with a Click to WhatsApp’s call-to-action:
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [
{
"id" : "ID" ,
"changes" : [
{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "PHONE_NUMBER" ,
"phone_number_id" : "PHONE_NUMBER_ID"
} ,
"contacts" : [
{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : "ID"
}
] ,
"messages" : [
{
"referral" : {
"source_url" : "AD_OR_POST_FB_URL" ,
"source_id" : "ADID" ,
"source_type" : "ad or post" ,
"headline" : "AD_TITLE" ,
"body" : "AD_DESCRIPTION" ,
"media_type" : "image or video" ,
"image_url" : "RAW_IMAGE_URL" ,
"video_url" : "RAW_VIDEO_URL" ,
"thumbnail_url" : "RAW_THUMBNAIL_URL" ,
"ctwa_clid" : "CTWA_CLID"
} ,
"from" : "SENDER_PHONE_NUMBERID" ,
"id" : "wamid.ID" ,
"timestamp" : "TIMESTAMP" ,
"type" : "text" ,
"text" : {
"body" : "BODY"
}
}
]
} ,
"field" : "messages"
}
]
}
]
} Flow completed
When the user completes the flow, a message is sent to WhatsApp chat. You will receive that message through a webhook which you normally use to process chat messages from the user.
Copy {
"messages" : [{
"context" : {
"from" : "16315558151" ,
"id" : "gBGGEiRVVgBPAgm7FUgc73noXjo"
} ,
"from" : "<USER_ACCOUNT_NUMBER>" ,
"id" : "<MESSAGE_ID>" ,
"type" : "interactive" ,
"interactive" : {
"type" : "nfm_reply" ,
"nfm_reply" : {
"name" : "flow" ,
"response_json" : {
"flow_token" : "<FLOW_TOKEN>" ,
"optional_param1" : "<value1>" ,
"optional_param2" : "<value2>"
}
}
} ,
"timestamp" : "<MESSAGE_SEND_TIMESTAMP>"
}]
} Request_message
See Conversational Components .
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [
{
"id" : "<WHATSAPP_BUSINESS_ACCOUNT_ID>" ,
"changes" : [
{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "<BUSINESS_DISPLAY_PHONE_NUMBER>" ,
"phone_number_id" : "<BUSINESS_PHONE_NUMBER_ID>"
} ,
"contacts" : [
{
"profile" : {
"name" : "<WHATSAPP_USER_NAME>"
} ,
"wa_id" : "<WHATSAPP_USER_ID>"
}
] ,
"messages" : [
{
"from" : "<WHATSAPP_USER_PHONE_NUMBER>" ,
"id" : "<WHATSAPP_MESSAGE_ID>" ,
"timestamp" : "<TIMESTAMP>" ,
"type" : "request_welcome" // Indicates first time message from WhatsApp user
}
]
} ,
"field" : "messages"
}
]
}
]
} Product Inquiry Messages
A Product Inquiry Message is received when a customer asks for more information about a product. These can happen when:
a customer accesses a business's catalog via another entry point, navigates to a Product Details page, and clicks Message Business about this Product .
A webhooks notification for a Product Inquiry Message looks like this:
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [
{
"id" : "ID" ,
"changes" : [
{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "PHONE_NUMBER" ,
"phone_number_id" : "PHONE_NUMBER_ID" ,
} ,
"contacts" : [
{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : "PHONE_NUMBER_ID"
}
] ,
"messages" : [
{
"from" : "PHONE_NUMBER" ,
"id" : "wamid.ID" ,
"text" : {
"body" : "MESSAGE_TEXT"
} ,
"context" : {
"from" : "PHONE_NUMBER" ,
"id" : "wamid.ID" ,
"referred_product" : {
"catalog_id" : "CATALOG_ID" ,
"product_retailer_id" : "PRODUCT_ID"
}
} ,
"timestamp" : "TIMESTAMP" ,
"type" : "text"
}
]
} ,
"field" : "messages"
}
]
}
]
} Order Messages
See Order Details Template Messages
A webhooks notification for when a customer places an order looks like this:
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [
{
"id" : "8856996819413533" ,
"changes" : [
{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "16505553333" ,
"phone_number_id" : "phone-number-id" ,
} ,
"contacts" : [
{
"profile" : {
"name" : "Kerry Fisher"
} ,
"wa_id" : "16315551234"
}
] ,
"messages" : [
{
"from" : "16315551234" ,
"id" : "wamid.ABGGFlCGg0cvAgo6cHbBhfK5760V" ,
"order" : {
"catalog_id" : "the-catalog_id" ,
"product_items" : [
{
"product_retailer_id" : "the-product-SKU-identifier" ,
"quantity" : "number-of-item" ,
"item_price" : "unitary-price-of-item" ,
"currency" : "price-currency"
} ,
...
] ,
"text" : "text-message-sent-along-with-the-order"
} ,
"context" : {
"from" : "16315551234" ,
"id" : "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
} ,
"timestamp" : "1603069091" ,
"type" : "order"
}
]
} ,
"field" : "messages"
}
]
}
]
} User Changed Number Notification
When a user changes their phone number on WhatsApp, you receive a system message notification:
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : PHONE_NUMBER ,
"phone_number_id" : PHONE_NUMBER_ID
} ,
"messages" : [{
"from" : PHONE_NUMBER ,
"id" : "wamid.ID" ,
"system" : {
"body" : "NAME changed from PHONE_NUMBER to PHONE_NUMBER" ,
"new_wa_id" : NEW_PHONE_NUMBER ,
"type" : "user_changed_number"
} ,
"timestamp" : TIMESTAMP ,
"type" : "system"
}]
} ,
"field" : "messages"
}]
}]
} Template held for Pacing
Example Payload Messages will have one of the following statuses which will be returned in each of the messages objects
"message_status":"accepted"
"message_status":"held_for_quality_assessment"
Copy {
"messaging_product" : "whatsapp" ,
"contacts" : [
{
"input" : "16505555555" ,
"wa_id" : "16505555555"
}
] ,
"messages" : [
{
"id" : "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA" ,
"message_status" : "Message has been held because quality assessment is pending" ,
//"message_status": "accepted",
}
]
}
Message Status Updates
The Messaging webhook receives an event when the message is sent, delivered, and read.
The order of these events may not reflect the actual timing of the message status. View the timestamp to determine the timing, if necessary.
Status: Message Sent
The following notification is received when a business sends a message as part of a user-initiated conversation (if that conversation did not originate in a free entry point):
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "PHONE_NUMBER" ,
"phone_number_id" : "PHONE_NUMBER_ID"
} ,
"statuses" : [{
"id" : "wamid.ID" ,
"status" : "sent" ,
"timestamp" : TIMESTAMP ,
"recipient_id" : PHONE_NUMBER ,
"conversation" : {
"id" : "CONVERSATION_ID" ,
"expiration_timestamp" : TIMESTAMP ,
"origin" : {
"type" : "referral_conversion"
}
} ,
"pricing" : {
"billable" : false ,
"pricing_model" : "CBP" ,
"category" : "referral_conversion"
}
}]
} ,
"field" : "messages"
}]
}]
} The following notification is received when a business sends a message in reply to a user-initiated conversation originating from free entry points :
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "PHONE_NUMBER" ,
"phone_number_id" : "PHONE_NUMBER_ID"
} ,
"statuses" : [{
"id" : "wamid.ID" ,
"recipient_id" : "PHONE_NUMBER" ,
"status" : "sent" ,
"timestamp" : "TIMESTAMP" ,
"conversation" : {
"id" : "CONVERSATION_ID" ,
"expiration_timestamp" : TIMESTAMP ,
"origin" : {
"type" : "business_initated"
}
} ,
"pricing" : {
"pricing_model" : "CBP" ,
"billable" : true ,
"category" : "business_initated"
}
}]
} ,
"field" : "messages"
}]
}]
} The following notification is received when a business sends a message as part of a business-initiated conversation :
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [
{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [
{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "BUSINESS_DISPLAY_PHONE_NUMBER" ,
"phone_number_id" : "BUSINESS_PHONE_NUMBER_ID"
} ,
"statuses" : [
{
"id" : "WHATSAPP_MESSAGE_ID" ,
"status" : "sent" ,
"timestamp" : "TIMESTAMP" ,
"recipient_id" : "CUSTOMER_PHONE_NUMBER" ,
"conversation" : {
"id" : "CONVERSATION_ID" ,
"expiration_timestamp" : "CONVERSATION_EXPIRATION_TIMESTAMP" ,
"origin" : {
"type" : "user_initiated"
}
} ,
"pricing" : {
"billable" : true ,
"pricing_model" : "CBP" ,
"category" : "service"
}
}
]
} ,
"field" : "messages"
}
]
}
]
} Status: Message Delivered
The following notification is received when a business’ message is delivered and that message is part of a user-initiated conversation (if that conversation did not originate in a free entry point ):
Copy {
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"statuses": [{
"id": "wamid.ID",
"recipient_id": "PHONE_NUMBER",
"status": "delivered",
"timestamp": "TIMESTAMP",
"conversation": {
"id": "CONVERSATION_ID",
"expiration_timestamp": TIMESTAMP,
"origin": {
"type": "user_initiated"
}
},
"pricing": {
"pricing_model": "CBP",
"billable": true,
"category": "service"
}
}]
},
"field": "messages"
}]
}]
The following notification is received when a business’ message is delivered and that message is part of a business-initiated conversation :
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "PHONE_NUMBER" ,
"phone_number_id" : "PHONE_NUMBER_ID"
} ,
"statuses" : [{
"id" : "wamid.ID" ,
"recipient_id" : "PHONE_NUMBER" ,
"status" : "delivered" ,
"timestamp" : "TIMESTAMP" ,
"conversation" : {
"id" : "CONVERSATION_ID" ,
"expiration_timestamp" : TIMESTAMP ,
"origin" : {
"type" : "business_initiated"
}
} ,
"pricing" : {
"pricing_model" : "CBP" ,
"billable" : true ,
"category" : "business-initiated"
}
}]
} ,
"field" : "messages"
}]
}]
} The following notification is received when a business’ message is delivered and that message is part of a user-initiated conversation originating from a free entry point :
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "PHONE_NUMBER" ,
"phone_number_id" : "PHONE_NUMBER_ID"
} ,
"statuses" : [{
"id" : "wamid.ID" ,
"status" : "sent" ,
"timestamp" : "TIMESTAMP" ,
"recipient_id" : "PHONE_NUMBER" ,
"conversation" : {
"id" : "CONVERSATION_ID" ,
"expiration_timestamp" : TIMESTAMP ,
"origin" {
"type" : "referral_conversion"
}
} ,
"pricing" : {
"billable" : false ,
"pricing_model" : "CBP" ,
"category" : "referral_conversion"
}
}]
} ,
"field" : "messages"
}]
}]
} Status: Message Read
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [
{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [
{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "BUSINESS_DISPLAY_PHONE_NUMBER" ,
"phone_number_id" : "BUSINESS_PHONE_NUMBER_ID"
} ,
"statuses" : [
{
"id" : "WHATSAPP_MESSAGE_ID" ,
"status" : "read" ,
"timestamp" : "TIMESTAMP" ,
"recipient_id" : "CUSTOMER_PHONE_NUMBER"
}
]
} ,
"field" : "messages"
}
]
}
]
} Status: Message Deleted
Currently, the Cloud API does not support webhook status updates for deleted messages. If a user deletes a message, you will receive a webhook with an error code for an unsupported message type:
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [{
"id" : "WHATSAPP_BUSINESS_ACCOUNT_ID" ,
"changes" : [{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : PHONE_NUMBER ,
"phone_number_id" : PHONE_NUMBER
} ,
"contacts" : [{
"profile" : {
"name" : "NAME"
} ,
"wa_id" : PHONE_NUMBER
}] ,
"messages" : [{
"from" : PHONE_NUMBER ,
"id" : "wamid.ID" ,
"timestamp" : TIMESTAMP ,
"errors" : [{
"code" : 131051 ,
"details" : "Message type is not currently supported" ,
"title" : "Unsupported message type"
}] ,
"type" : "unsupported"
}]
} ,
"field" : "messages"
}]
}]
} Please note that there are other user behaviors that can trigger this same error message. See Error Messages .
Status: Message Failed
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [
{
"id" : "<WHATSAPP_BUSINESS_ACCOUNT_ID>" ,
"changes" : [
{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "15550783881" ,
"phone_number_id" : "106540352242922"
} ,
"statuses" : [
{
"id" : "wamid.HBgLMTIxMTU1NTc5NDcVAgARGBIyRkQxREUxRDJFQUJGMkQ3NDIA" ,
"status" : "failed" ,
"timestamp" : "1689380458" ,
"recipient_id" : "15551234567" ,
"errors" : [
{
"code" : 131014 ,
"title" : "Request for url https://URL.jpg failed with error: 404 (Not Found)"
}
]
}
]
} ,
"field" : "messages"
}
]
}
]
} Status: Message Undeliverable (Experiments)
See Experiments in Marketing Messages.
Copy {
"object" : "whatsapp_business_account" ,
"entry" : [
{
"id" : "102290129340398 " ,
"changes" : [
{
"value" : {
"messaging_product" : "whatsapp" ,
"metadata" : {
"display_phone_number" : "15550783881" ,
"phone_number_id" : "106540352242922"
} ,
"statuses" : [
{
"id" : "wamid.HBgLMTIxMTU1NTc5NDcVAgARGBIyRkQxREUxRDJFQUJGMkQ3NDIA" ,
"status" : "failed" ,
"timestamp" : "1689380458" ,
"recipient_id" : "15551234567" ,
"errors" : [
{
"code" : 130472 ,
"title" : "User's number is part of an experiment" ,
"message" : "User's number is part of an experiment" ,
"error_data" : {
"details" : "Failed to send message because this user's phone number is part of an experiment"
} ,
"href" : "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
}
]
}
]
} ,
"field" : "messages"
}
]
}
]
}
