Delivery Notifications
When a message is sent by business using API Call, its generally accepted by WhatsApp for processing if complies to JSON format specification.
Message Accepted Response
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 in JSON format as given below:
{"status": "processing","message_id": "{message id}"}
Delivery Notification Posts
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.
Standard 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}"}
JSON Explaination Format
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. |
A Sample JSON Post
Given JSON Payload carries common keys/objects of a delivery 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 Object of statuses
Array 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 |
Type of Status Updates
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}"}
JSON 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.
<?phpheader("HTTP/1.1 200 OK");?>