When a message is sent out to user or customer by Business suing API, related delivery notification for the message is posted to Webhook at real time with predefined JSON format.
Table of Contents
Overview
When a message is sent by business using API Call, its generally accepted by WhatsApp for processing if complies to JSON format specification.
Success Response JSON: When a message is sent using API, WhatsApp accepts for processing and message is assigned with a message_id which is returned in the API Call response as given below:
{
"status": "processing",
"message_id": "{message id}"
}
Once its accepted, WhatsApp tries to deliver the message to user or customer. Therefore, status of the message is updated time to time. Subsequently all delivery status updates are posted to the Webhook against this message_id. With all delivery notification, WhatsApp returns the extra key field that is used by you to pass your custom data. This helps in effective processing of notification to take action at Application level as per business requirement.
Delivery Notification JSON Format
In Single Delivery Notification post will have array of objects in its JSON Payload Each object contains details of a single message sent out to a recipient. The JSON payload carries the following 2 sections:
{
"statuses": [
{
// Message Status Infomration
}
],
"business_phone": "{business phone}"
}
| Key / Object | Data Type | Description |
|---|---|---|
| statuses | Array | Array of Objects. Each Object carries delivery information of a single message |
business_phone | String | Business Phone Number which was used to send message. |
Sample JSON Format: Given JSON Payload carries common keys/objects of a Status Notification
{
"statuses": [
{
"id": "{request id}",
"recipient_id": "{recipient phone}",
"status": "sent",
"timestamp": "{unix timestamp}",
"type": "message",
"extra": "{custom data}"
}
],
"business_phone": "{business phone}"
}
A Single Delivery Status Object: A single status object which is contained in the statuses array is explained below.
| Key / Object | Data Type | Description |
|---|---|---|
id | String | Request ID. This notification is related to the Request ID assigned to a message sent by API earlier. |
recipient_id | String | Recipient Phone Number with Country Code (Without + Sign) |
status | String | Status of the message. Enumerated data: sent, delivered, failed, warning, read |
timestamp | String | Unix Timestamp in UTC |
| type | String | For message delivery notification, it carries message, |
Following section explains JSON Payload Format received at the Webhook for different type of Status updates.
Message Sent Notification
A notification with sent status means the message is in transit to get delivered to recipient.
JSON Payload:
{
"statuses": [
{
"id": "{request id}",
"recipient_id": "{recipient phone}",
"status": "sent",
"timestamp": "{unix timestamp}",
"type": "message",
"conversation": {
"id": "{conversation id}",
"expiration_timestamp": "{unix timestamp}",
"origin": {
"type": "{user_initiated / business_initiated}"
}
},
"extra": "{custom data}"
}
],
"business_phone": "{business phone}"
}
Payload Explanation: For Common Key/Objects, refer explanation given above. Following table explains sent status related keys/objects only.
| Key / Object | Data Type | Description |
|---|---|---|
status | String | For a Message sent notification, it carries sent. |
conversation | Object | It appears with sent and delivered message notifications of the first message sent by business that initiates the conversation. This carries conversation information. |
| conversation.id | String | Conversation ID. You get reported on this data. |
conversation. expiration_timestamp | String | Unix Timestamp in UTC. It shows the time when the current conversation expires or ends. |
conversation. origin.type | String | Enumerated. Its either business_Initiated or user_initiated. |
Message Delivered Notification
A notification with delivered status means the message got delivered to the recipient’s phone.
JSON Payload:
{
"statuses": [
{
"id": "{request id}",
"recipient_id": "{recipient phone}",
"status": "delivered",
"timestamp": "{unix timestamp}",
"type": "message",
"extra": "{custom data}"
}
],
"business_phone": "{business phone}"
}
Payload Explanation: For Common Key/Objects, refer explanation given above. Following table explains delivered status related keys/objects only.
| Key / Object | Data Type | Description |
|---|---|---|
status | String | For a Message delivered notification, it carries delivered. |
Message Read Notification
A notification with read status means the delivered message is read by the recipient.
JSON Payload:
{
"statuses": [
{
"id": "{request id}",
"recipient_id": "{recipient phone}",
"status": "read",
"timestamp": "{unix timestamp}",
"type": "message",
"extra": "{custom data}"
}
],
"business_phone": "{business phone}"
}
Payload Explanation: For Common Key/Objects, refer explanation given above. Following table explains read status related keys/objects only.
| Key / Object | Data Type | Description |
|---|---|---|
status | String | For a Message read notification, it carries read. |
Message Failed Notification
A message sent by business failed in processing or failed to deliver. A reason for the failure will be included in Webhook notification with an Error Code.
JSON Payload:
{
"statuses": [
{
"id": "{request id}",
"recipient_id": "{recipient phone}",
"status": "failed",
"timestamp": "{unix timestamp}",
"type": "message",
"errors": [
{
"code": {error code},
"title": "{error title}",
"details": "{error description}"
}
],
"extra": "{custom data}"
}
],
"business_phone": "{business phone}"
}
Payload Explanation: For Common Key/Objects, refer explanation given above. Following table explains failed status related keys/objects only.
| Key / Object | Data Type | Description |
|---|---|---|
status | String | For a Message failed notification, it carries failed. |
| errors | Array | Array of Objects. It contains each error as Object. This Array appears appears only with failed notifications. This carries error information information. |
errors[n].code | String | Error Code |
errors[n].title | String | Error Title |
errors[n].details | String | Error Description |
Acknowledgement
Any delivery notification 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");
?>