Incoming Messages

When a user sends a message to Business, its posted to Webhook at real time with a JSON Payload of predefined format. .

Table of Contents

• Overview
• Message JSON Format Explanation
• JSON for different type of Contents
  • Text
  • Image
  • Video
  • Audio & Voice
  • Document
  • Location
  • Contact
  • Sticker
• Acknowledgement

Overview

Incoming Messages, either user-originated or responses to business-originated messages are received through Webhook.

Incoming Message JSON Format Explanation

Whether its user-initiated message or follow-up message from a user, incoming messages with different type of content will have common JSON format as given below:

{
  "messages": [
    {
      "id": "{message id}",
      "from": "{sender phone}",
      "timestamp": "{unix timestamp}",
      "type": "{content type}",
      "{content type}": {
	/* content type specific information */
      }
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "{sender name}"
      },
      "wa_id": "{sender phone}"
    }
  ],
  "business_phone": "{business phone}" 
}

Incoming Message JSON Explanation

Key / Object	Data Type	Description
messages	Array	Its presented as array of messages. The message information will appear as an object in it.
contacts	Array	Its message sender profile. Its presented as array of senders. For incoming message, sender is the user or customer who sent message using WhatsApp App to business
business_phone	String	Business Phone Number to which the message is sent by user or customer.

A Single Message Object: Its related to the message information placed in messages array in incoming message payload.

Key / Object	Data Type	Description
id	String	Message ID. All Action, reactions will be received on this ID.
from	String	Sender Phone Number
timestamp	String	Unix Timestamp for the message in UTC
type	String	Type of content. Enumerated data. e.g. audio, contacts, document, image, location, text, video
$type	String	This key is named after the type explained above. For example, if type=image, this this object name will be image and it will contain related information. Later in the document, we have different section to explain each of this object content.

A Single Contact Object: Its related to the Sender Profile placed in contacts array in incoming message payload.

Key / Object	Data Type	Description
profile	Object	Its sender profile information
profile.name	String	Sender Name
wa_id	String	WhatsApp ID i.e. Sender Phone Number including country code

JSON Explanation for different type of content

Read the following section to understand different type of incoming messages and related JSON received on Webhook.

Text Message

JSON Payload

{
  "messages": [
    {
      "id": "{message id}",
      "from": "{sender phone}",
      "timestamp": "{unix timestamp}",
      "type": "text",
      "text": {
	  "body": "{text contents}"
      }
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "{sender name}"
      },
      "wa_id": "{sender phone}"
    }
  ],
  "business_phone": "{business phone}" 
}

Text Specific Explanation: Covers only key/objects related to Text Content. For other keys, refer explanation given above.

Key / Object	Data Type	Description
type	String	It comes as text
text	Object	This object appears with type:text. It contains text content information
text.body	String	Text content for the message body

Message with Image

JSON Payload

{
  "messages": [
    {
      "id": "{message id}",
      "from": "{sender phone}",
      "timestamp": "{unix timestamp}",
      "type": "image",
      "image": {
	  "mime_type": "{file mime type}",
          "sha256": "{sha256}",
          "id": "{media file id}",
         "caption": "{image caption",
      }
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "{sender name}"
      },
      "wa_id": "{sender phone}"
    }
  ],
  "business_phone": "{business phone}"
}

Image Specific Explanation: Covers only key/objects related to Image Content. For other keys, refer explanation given above.

Key / Object	Data Type	Description
type	String	It comes as image
image	Object	This object appears with type:image. It contains image content information
image.mime_type	String	Mime type of image, e.g. image/jpeg
image.sha256	String	SHS265 Hash
image.id	String	ID of the image. Use it to get Image Content through Get Media API
image.caption	String	Optional. Caption for the image.

Message with Video

JSON Payload

{
  "messages": [
    {
      "id": "{message id}",
      "from": "{sender phone}",
      "timestamp": "{unix timestamp}",
      "type": "video",
      "video": {
	  "mime_type": "{file mime type}",
          "sha256": "{sha256}",
          "id": "{media file id}",
          "caption": "{video caption}",
         "filename": "{name of the file}"
      }
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "{sender name}"
      },
      "wa_id": "{sender phone}"
    }
  ],
  "business_phone": "{business phone}"
}

Video Specific Explanation: Covers only key/objects related to Video Content. For other keys, refer explanation given above.

Key / Object	Data Type	Description
type	String	It comes as video
video	Object	This object appears with type:video. It contains image content information
video.mime_type	String	Mime type of video, e.g. video/mp4
video.sha256	String	SHA265 Hash for Image
video.id	String	ID of the Video. Use it to get Video Content through Get Media API
video.caption	String	Optional. Caption for the Video.
video.filename	String	The name for the file on the sender’s device.

Message with Audio & Voice

Difference between Audio and Voice Content is related to how the audio content is added into the message by the sender. A sender using WhatsApp can pick a Audio file from File Manager to send as message is called a Audio type of content. Whereas when sender records a voice to send over as a message is called a Voice Message. In either case, at the receiver end (In this case its the business receiving the message) the message always comes in form of a Audio File.

JSON Payload

{
  "messages": [
    {
      "id": "{message id}",
      "from": "{sender phone}",
      "timestamp": "{unix timestamp}",
      "type": "audio",
      "audio": {
	  "mime_type": "{file mime type}",
          "sha256": "{sha256}",
          "id": "{media file id}",
          "voice": "{boolean true/false}" 
      }
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "{sender name}"
      },
      "wa_id": "{sender phone}"
    }
  ],
  "business_phone": "{business phone}"
}

Audio/Voice Specific Explanation: Covers only key/objects related to Audio/Voice Content. For other keys, refer explanation given above.

Key / Object	Data Type	Description
type	String	It comes as audio
audio	Object	This object appears with type:audio. It contains image content information
audio.mime_type	String	Mime type of audio, e.g. audio/mp3
audio.sha256	String	SHS265 Hash
audio.id	String	ID of the Audio/Voice file. Use it to get Audio Content through Get Media API
audio.voice	Boolean	It comes as true for Voice message, and comes as false for Audio File message

Message with Document

JSON Payload

{
  "messages": [
    {
      "id": "{message id}",
      "from": "{sender phone}",
      "timestamp": "{unix timestamp}",
      "type": "document",
      "document": {
	  "filename": "{file name with extension}",
	  "mime_type": "{file mime type}",
          "sha256": "{sha256}",
          "id": "{file id}" 
      }
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "{sender name}"
      },
      "wa_id": "{sender phone}"
    }
  ],
  "business_phone": "{business phone}"
}

Document Specific Explanation: Covers only key/objects related to Document Content. For other keys, refer explanation given above.

Key / Object	Data Type	Description
type	String	It comes as document
document	Object	This object appears with type:document. It contains document content information
document.mime_type	String	Mime type of image, e.g. image/jpeg
document.filename	String	File name with extension
document.sha256	String	SHS265 Hash
document.id	String	ID of the Document. Use it to get Document Content through Get Media API

Message with Location

JSON Payload

{
  "messages": [
    {
      "id": "{message id}",
      "from": "{sender phone}",
      "timestamp": "{unix timestamp}",
      "type": "location",
      "location": {
	  "latitude": "{latitude of location}",
	  "longitude": "{longitude of location}",
          "name": "{name of location}",
          "address": "{addrees of location}"
      }
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "{sender name}"
      },
      "wa_id": "{sender phone}"
    }
  ],
  "business_phone": "{brand phone}"
}

Location Specific Explanation: Covers only key/objects related to Location Content. For other keys, refer explanation given above.

Key / Object	Data Type	Description
type	String	It comes as location
location	Object	This object appears with type:location. It contains location information
location.latitude	String	Latitude for location
location.longitude	String	Longitude for location
location.name	String	Name of location
location.address	String	Address of location

Message with Contact

JSON Payload

{
  "messages": [
    {
      "id": "{message id}",
      "from": "{sender phone}",
      "timestamp": "{unix timestamp}",
      "type": "contacts",
      "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}"
              }
            ]
          }
        ]
      }
    ],   
  "contacts": [
    {
      "profile": {
        "name": "{sender name}"
      },
      "wa_id": "{sender phone}"
    }
  ],
  "business_phone": "{brand phone}" 
}

Contact Specific Explanation: Covers only key/objects related to Contacts Content. For other keys, refer explanation given above.

Key / Object	Data Type	Description
type	String	It comes as contacts
contacts	Object	This object appears with type:contact. It contains location information
contacts.addresses	Array	Array of objects. Each Object is Address
contacts.birthday	String	Date of Birth
contacts.emails	Array	Array of Objects. Each Object is an Email Address
contacts.name	Object	Name. It breaks down name into parts defined as keys
contacts.org	Object	Organization
contacts.phones	Array	Array of Objects. Each Objec is a Phone Number
contacts.urls	Object	URL of different type/category

Message with Sticker

JSON Payload

{
  "messages": [
    {
      "id": "{message id}",
      "from": "{sender phone}",
      "timestamp": "{unix timestamp}",
      "type": "sticker",
      "sticker": {
	  "mime_type": "{file mime type}",
          "sha256": "{sha256}",
          "id": "{media file id}",
         "animated": "{boolean}",
      }
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "{sender name}"
      },
      "wa_id": "{sender phone}"
    }
  ],
  "business_phone": "{business phone}"
}

Image Specific Explanation: Covers only key/objects related to Image Content. For other keys, refer explanation given above.

Key / Object	Data Type	Description
type	String	It comes as sticker
sticker	Object	This object appears with type:image. It contains sticker information
sticker.mime_type	String	Mime type of image, i.e. image/webp
sticker.sha256	String	SHS265 Hash for the Sticker
sticker.id	String	ID of the Sticker. Use it to get Sticker Content through Get Media API
sticker.animated	Boolean	Its true if the sticker is animated; false otherwise.

Acknowledgement

Any Message received at Webhook must be acknowledged by returning HTTP 200 header in the same connection.

Refer the example below written in PHP, to return HTTP 200 header.

<?php
header("HTTP/1.1 200 OK");
?>