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 Notifications

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.

Example: Text Message Received

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

Example: Static Location Message Received

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

Example: Contacts Message Received

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",
                    "contact_image": "/9j/4AAQSkZJRgABAQEAZABkAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCABgAGADASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD1NLloxyc0j3bNUHDGgoCMVNkBbhutvVqc9yGHNZ3kOW4Wn/ZnQZzSsgLLXAA61Xn1O2t4zLcyJHGvV3OAKMADmvOviLq9m11a2bO/l2xLzoqnliF2j9f1NTLRXHGHM7Hb2vivSL+8e0s7yKaVeyHg/Q9D+FXWuHPOzivFodT0WZkeF44bheVdE2EH+Rr2+zuVuNPt7gqh86JX+TkcjPFTCdy6lNQ2dyr5+G5WpRe4HTFWWSOQfwioZbCIn5XNaXRmQPegjmqrKLh+...",
                    "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"
        }
    ]
}

Examples: 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: Unknown 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 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 and the WhatsApp ID of the sender of the original message.

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.

Inbound System Messages

System messages are generated by the system when some event happens. See the system object section below for more information.

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

Parameters and Fields for Inbound Messages

As shown in the examples in this document, Webhook notifications of received messages are contained within a messages object. The tables in this section describe the fields in the inbound notifications.

NameDescription

contacts

type: Array of contact profile information

Contacts Object

messages

type: Array of any type of message objects

Messages Object

The contacts object

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.

The profile object

NameDescription

name

type: String

Optional.

Contains the sender's profile name

The messages object

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.

from

type: String

WhatsApp ID of the sender

id

type: String

Message ID

identity

type: Identity Object

Optional.
Contains information about the user identity used to decrypt the incoming message
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
Values: audio, contacts, document, image, location, text, unknown, video, voice

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

type: Message type objects that provide more information about the received message. See the media object fields for more information.

Message contents

system

type: System Object

Notifications of changes to the system

The context object

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

NameDescription

from

type: String

WhatsApp ID of the sender of the original message

id

type: String

Message ID of original message

The identity object

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

The text object

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

NameDescription

body

type: String

Message text

The location object

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.

The contacts object

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

contact_image

type: Base64-encoded image

Bas64-encoded contact image in JPEG format

emails

type: Array

Contact email address(es)
Can contain email and type fields.

ims

type: Array

Messaging contact information
Contains service and user_id fields.

name

type: Array

Full contact name
Can contain first_name, middle_name, last_name, formatted_name, name-prefix, and name_suffix fields.

org

type: Array

Contact organization information
Can contain company, department, and title fields.

phones

type: Array

Contact phone number(s)
Can contain phone, wa_id, and type fields.

urls

type: Array

Contact URL(s)
Can contain url and type fields.

The media (image | document | audio | video | voice | sticker) objects

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

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

The system object

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

NameDescription

body

type: String

System event message

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

You can use the messages node to change the status of incoming messages to read.

Prerequisites

  • You must set pass_through to false in the application settings.
    Note: When you set the flag for first time, you must restart the Coreapp to reflect this change.

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.

Request

The message_id used in this API call is the id provided in the inbound notification.

PUT /v1/messages/message-id

{
    "status": "read"
}

Parameters

NameDescription

status

Required.

Updating status to read is applicable only for incoming messages.

Response

null # or {}