WhatsApp Business API

Inbound Notifications

There are several types of inbound notifications that may be delivered to your unique Webhook.

This document covers:

For more general Webhook information, see:

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 messages and location messages.

Example: Text Message Received

The following is an example of a text message you 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 you 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 you 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"
                        }
                    ],
                    "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"
        }
    ]
}

Example: Unknown Message Received

Beginning with v2.21.3 it is possible to receive an unknown callback notification. The following is an example of a message you received from a customer that is not supported.

{
  "messages": [{
          "errors": [
              {
                  "code": 501,
                  "details": "Message type is not currently supported",
                  "title": "Unknown message type"
              }
          ],
          "from": "16315551234",
          "id": "ABGGFRBzFymPAgo6N9KKs7HsN6eB",
          "timestamp": "1531933468",
          "type": "unknown"
      }]
}

Inbound Media Message Notifications

When a message with media is received, the WhatsApp Business API Client will download the media. A notification is sent to your Webhook once the media is downloaded. This message 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"}
  }]
}

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.

User Deleted Message

Beginning with v2.21.3, in the case where a user deletes a message they have sent to you, you will receive a message status notification indicating the message was deleted. The message will be deleted automatically from the WhatsApp server, but please ensure that the message is also deleted from your system if it was downloaded. See Message Maintenance for more information on how to do this.

Inbound System Messages

System messages are generated by the system when some event happens, for example a user added/removed another user or leaves a group, etc. See the system object section below for more information.

{
    "messages": [
        {
            "from": "16506448470",
            "group_id": "16315558032-1530825318",
            "id": "ACELFjFVWAMqFTCCUxgDM3N5cy0xNjMxNTU1ODAzMi0xNTMwODI1MzE4QGcudXMtMTUzMDgyNTU4NzI5OS1hZGQtMBGGFlBkSEcP",
            "system": {
                "body": "+1 (650) 387-5246 added +1 (650) 644-8470",
                "group_id": "16315558032-1530825318",
                "operator": "16503875246",
                "type": "group_user_joined",
                "users": [
                    "16506448470"
                ]
            },
            "timestamp": "1530825587",
            "type": "system"
        }
    ]
}

For example, the following system messages were received when (1) a user joined a group and (2) when a group administrator added a group icon.

Message received: {"messages":[{"from":"12345678901","group_id":"16315558011-1521728362","id":"gBEGkYiEB1VXAglK1ZEqA1YKPrU","system":{"body":"‎‎+1 (234) 567-8901 was added‎"},"timestamp":"1521739514","type":"system"}]}

Message received: {"messages":[{"from":"16315558011","group_id":"16315558011-1521728362","id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf","system":{"body":"‎‎+1 (631) 555-8011 changed this group's icon‎"},"timestamp":"1521745780","type":"system"}]}

System Message Types

System Message TypeDescription

group_created

Group created

group_user_promoted

Group user promoted to admin

group_user_demoted

Group user removed as admin

group_user_joined

User joined the group

group_user_left

User left the group

group_subject_changed

Group subject changed

group_description_changed

Group description changed

group_icon_changed

Group icon changed

group_icon_deleted

Group icon deleted

group_invite_link_revoked

Group's invite link disabled

user_identity_changed

User's end-to-end keys changed

group_user_changed_number

User's phone number changed

group_error_fetching_photo

Error retrieving the group photo

group_error_adding_users

Error adding users to the group

group_error_adding_user

Error adding a user to the group

group_error_full_adding_users

Group is at capacity and no more users can be added

group_error_removing_user

Error removing user from group

broadcast_list_created

Broadcast list created

group_ended

Group ended

group_error_blocked_adding_user

Error attempting to add a user that blocked the adder

Parameter/Field Descriptions for Inbound Messages

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

NameDescriptionType

contacts

Contacts Object

Array of Contact profile information

messages

Messages Object

Array of any type of message objects

The contacts object

The contacts object provides all the information about the contact.
Note: This object only applies to text, contacts, and location messages. It is not currently supported for media messages and not applicable for system messages.

NameDescriptionType

profile

As of v2.21.4, contains the sender's profile information.

Profile object

wa_id

The WhatsApp ID of the contact

String

The profile object

NameDescriptionType

name

Optional. As of v2.21.4, contains the sender's profile name.

String

The messages object

The messages object provides all of the information about the incoming message.

NameDescriptionType

context

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.

String

from

WhatsApp ID of the sender

String

group_id

Optional. WhatsApp group ID

String

id

Message ID

String

timestamp

Message received timestamp

String

type

Message type. Values include: audio, contacts, document, image, location, text, unknown, video, voice

String

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

Message contents

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

system

Notifications of changes to the system

System Object

The context object

A context object is found in messages where someone has replied to your message. Its purpose is to provide you with a context for the reply.

NameDescriptionType

from

WhatsApp ID of the sender of the original message

String

id

Message ID of original message

String

The text object

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

NameDescriptionType

body

Message text

String

The location object

When you receive a notification of a user's static location, the location object provides the details of the location.

NameDescriptionType

latitude

Latitude of location being sent

Number

longitude

Longitude of location being sent

Number

address

Address of the location

String

name

Name of the location

String

url

URL for the website where the user downloaded the location information

String

Inbound messages of type live location are not currently supported.

The contacts object

Beginning with v2.21.3, 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.

NameDescriptionType

addresses

Full contact address(es). Each address can contain street, city, state, zip, country, country_code, and type fields.

Array

birthday

Contact's birthday

YYYY-MM-DD formatted string

emails

Contact email address(es). Each emails object can contains email and type fields.

Array

name

Full contact name. Each name object can contain first_name, middle_name, last_name, formatted_name, name-prefix, and name_suffix fields.

Array

org

Contact organization information. Each org object can contain company, department, and title fields.

Array

phones

Contact phone number(s). Each phones object can contain phone, wa_id, and type fields.

Array

urls

Contact URL(s). Each urls object can contain url and type fields.

Array

The media (image | document | audio | video | voice) 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.

NameDescriptionType

caption

Optional. Only present if specified.

String

file

Absolute filename and location on media volume. This parameter is deprecated.

String

filename

Filename on the sender's device. This will only be present in audio and document media messages.

String

id

ID of the media. Can be used to delete the media if stored locally on the client.

String

mime_type

Mime type of media

String

sha256

Checksum

String

The system object

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

NameDescriptionType

body

System event message

String

Mentioning Users in Messages

When you send a message that mentions a particular WhatsApp ID directly and someone replies to that message, or if someone sends a group message and mentions you, you will see the mentioned ID in the context object and in the mentions array. Mentions are supported in groups. 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",
      "group_id": "16315551000-1994222729",
      "id": "gBGGFlA5FpafAgkOuJbRq54qwbM",
      "mentions": [
        "16315551000",
        "16315551099"
      ]
    },
    "from": "16315551234 ",
    "group_id": "16315551000-1994222729",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1504902988",
    "text": {
      "body": "@16315551000 and @16315551099 are mentioned"
    },
    "type": "text"
  }]
}

Example: Customer Mentions You in a Group Message

The following is an example of a customer mentioning you in a group message. You have to be a member of the group.

{
  "messages":[{
     "from":"16315555544",
     "group_id":"16315558011-1521728302",
     "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
     "text":{
        "body":"Mentioning @16315558011"},
     "timestamp":"1522191054",
     "type":"text"
  }]}

Marking Messages as Read

Beginning with v2.21.3 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. When you set the flag for first time, to reflect this change, please restart the coreapp.

Note: 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, messages are saved in local database until they are explicitly deleted.

Request

The message_id indicated is the id provided in the inbound notification.

PUT /v1/messages/message-id

{
    "status": "read"
}

Parameters

NameRequiredDescription

status

Yes

Updating status to read is applicable only for incoming messages.

Response

null # or {}