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 / ObjectData TypeDescription
statusesArrayArray of Objects. Each Object carries delivery information of a single message
business_phoneStringBusiness 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 / ObjectData TypeDescription
idStringRequest ID. This notification is related to the Request ID assigned to a message sent by API earlier.
recipient_idStringRecipient Phone Number with Country Code (Without + Sign)
statusStringStatus of the message. Enumerated data: sent, delivered, failed, warning, read
timestampStringUnix Timestamp in UTC
typeStringFor 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 / ObjectData TypeDescription
statusStringFor a Message sent notification, it carries sent.
conversationObjectIt appears with sent and delivered message notifications of the first message sent by business that initiates the conversation. This carries conversation information.
conversation.idStringConversation ID. You get reported on this data.
conversation. expiration_timestampStringUnix Timestamp in UTC. It shows the time when the current conversation expires or ends.
conversation. origin.typeStringEnumerated. 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 / ObjectData TypeDescription
statusStringFor 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 / ObjectData TypeDescription
statusStringFor 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 / ObjectData TypeDescription
statusStringFor a Message failed notification, it carries failed.
errorsArrayArray of Objects. It contains each error as Object. This Array appears appears only with failed notifications. This carries error information information.
errors[n].codeStringError Code
errors[n].titleStringError Title
errors[n].detailsStringError 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");
?>