Incoming Messages

When a user sends a message to Business, it's termed as Incoming Message for the business. Such messages are posted to to Webhook at real time with a JSON Payload of predefined format.

Note: Both user-originated message or responses to business-originated messages are received through Webhook.

Standard JSON Format

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

JSON Explanation

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

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

Type of Incoming Messages

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

JSON Explanation: Covers only key/objects related to 'text` Content. For other keys, refer explanation given above.

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

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

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

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

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

JSON Explanation: Covers only key/objects related to audio or voice Content. For other keys, refer explanation given above.

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

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

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

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

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

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

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

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

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");
?>