WhatsApp Business API

Inbound Webhook Notifications

This document describes the several types of inbound notifications that may be delivered to the Webhook URL you set in the application settings.

Inbound Message Fields

Webhook notifications of received messages are contained within a messages object. Your inbound notifications can also contain the following objects:

referral Property

Starting 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.

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.
  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 contain the following types of message:

  • Text
  • Location
  • Contact
  • Image
  • Video
  • Document
  • Voice
  • Sticker

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

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.

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. Opening this url takes you to the ad viewed by your user.

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.

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.

Inbound Message Notifications

This section shows examples of received messages.

Example: Text Message Received

The following is an example of a text message received from a customer.

{
  "contacts": [ {
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  } ],
  "messages":[{
    "from": "16315551234",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1518694235",
    "text": {
      "body": "Hello this is an answer"
    },
    "type": "text"
  }]
}

Example: Static Location Message Received

The following is an example of a message received from a customer specifying their static location.

{
  "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"
  }]
}

Example: Contacts Message Received

The following is an example of a message received from a customer specifying their contact 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"
        }
    ]
}

The contact_image setting is empty if the consumer client is using an IPhone.

Example: Forwarded Message Received

Beginning with v2.29.1 it is possible to see if a message you received has been forwarded or is frequently forwarded.

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"
    }]
}

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"
            }
    }]
}

Example: Unsupported Message Received

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"
	}]
}

Example: Inbound Message Received when a Business Has Opted in to Receive Security Notifications

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"
    }]
}

Example: Inbound Message From a Quick Reply Button Click

When your customer clicks on a quick reply button, a response is sent. Below is an example of the callback format. Note: A customer may not click a button and either reply to the interactive template message or just send you a message. Make sure that you are able to support this type of scenario as well. See the Webhooks documentation for more information. 
{
    "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": [ { ... } ]
}

Inbound Media Message Notifications

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.

Example: Message with Image Received

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.

Example: Message with Document Received

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"
		}
	}]

Example: Message with Voice Message Received

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"}
  }]
}

Example: Message with Sticker Received

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"
        }  
    }]
}

Inbound Replies to Sent Messages

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.

Example: Customer Replied to Your Message

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.

Example: Customer Replied to a List 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"
          }
      }
   }

Example: Customer Replied to a Reply Button 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": "button_reply",
        "button_reply": {
          "id": "unique-button-identifier",
          "title": "button-text"
        }
      } # end interactive node
    } # end message item
  ] # end messages array
}

Example: Customer Asking For Information About a Specific Product

{
  "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"
    }
  ]
}

Example: Customer placed an order after receiving a Multi or Single Product Message

{
   "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"
      }
   }
}

Inbound System Messages

System messages are generated by the system when some event happens.

Example: A User Changed Their Number

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"
        }
    ]
}

Example: A User Potentially Changed

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 Types

System Message TypeDescription

user_changed_number

User's phone number changed

user_identity_changed

User has potentially changed on WhatsApp

Mentioning Users in Messages

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.

Example: Customer Replying to Message

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"
  }]
}

Marking Messages as Read

When you receive an inbound message notification, you can update its status. See Mark Messages as Read for more information.