Delivery Report (DR) are webhooks for Messaging Apps delivery statuses: POST requests sent by the 8x8 platform in JSON format to the callback URL configured for your account.
Requirements
To use 8x8 Outbound Messaging Apps capabilities, you need:
- An account configured to use Messaging Apps product.
- A webhook to indicate to us which URL 8x8 platform should send delivery reports to.
You can configure your callback using Webhooks Configuration API
Retry logic
In case of connection error/timeout or HTTP response code 4XX or 5XX, there will be multiple retry attempts with progressive intervals: 1, 10, 30, 90 sec.
Read Receipt - Validity Period
If the chat app doesn't provide a read receipt promptly, either because the user hasn't read the message or due to a chat app service issue, we'll continue checking for up to 10 days. If the user reads the message after this period, the read receipt won't be updated.
Webhook format
Request body description
| Parameter name | Parameter type | Description |
|---|---|---|
| namespace | string | A generic namespace for incoming webhook. Equal to ChatApps for delivery receipts. |
| eventType | string | Webhook type. Equals to outbound_message_status_changed for delivery receipts |
| description | string | Human-readable description of the incoming event |
| payload | object | Delivery receipt information, see below |
Payload object description
| Parameter name | Parameter type | Description |
|---|---|---|
| umid | uuid | A unique identifier generated by 8x8 for the message |
| batchId | uuid | A unique identifier generated by 8x8 for the message if sent using Batch API |
| clientMessageId | string | Custom identifier you provided for this message |
| clientBatchId | string | Custom identifier you provided for this batch of messages |
| subAccountId | string | The sub-account id used to deliver the message |
| channel | string | Name of the channel used to send the message, please see List of supported Messaging Apps channels for details |
| user | object | Information about the user the message is associated with |
| status | object | Current status of the message, please see Message status reference for details |
User information object description
| Parameter name | Parameter type | Description |
|---|---|---|
| msisdn | string | Phone number expressed in E.164 international format |
| channelUserId | string | Channel user identifier |
Please note that unlike Delivery Receipts for the SMS API, the Price object is not sent for Messaging Apps Webhooks.
If the request you receive has a different structure from described in this document, please contact our support to activate the latest format for your account.
Sample delivery receipt for outbound message
{
"namespace": "ChatApps",
"eventType": "outbound_message_status_changed",
"description": "ChatApps outbound message delivery receipt",
"payload": {
"umid": <UNIQUE_MESSAGE_ID>,
"batchId": <BATCH_ID>,
"clientMessageId": <YOUR_MESSAGE_ID>,
"clientBatchId": <YOUR_BATCH_ID>,
"subAccountId": <SUBACCOUNT_ID>,
"channel": "whatsapp",
"user": {
"msisdn": "+6512345678",
"channelUserId": "6512345678"
},
"status": {
"state": "delivered",
"detail": "delivered_to_recipient",
"timestamp": "2025-05-05T09:15:57.00Z"
}
}
}
{
"namespace": "ChatApps",
"eventType": "outbound_message_status_changed",
"description": "ChatApps outbound message delivery receipt",
"payload": {
"umid": <UNIQUE_MESSAGE_ID>,
"batchId": <BATCH_ID>,
"clientMessageId": <YOUR_MESSAGE_ID>,
"clientBatchId": <YOUR_BATCH_ID>,
"subAccountId": <SUBACCOUNT_ID>,
"channel": "whatsApp",
"user": {
"msisdn": "+6512345678",
"channelUserId": "6512345678"
},
"status": {
"state": "read",
"timestamp": "2025-05-17T06:27:52.45Z"
}
}
}
{
"namespace": "ChatApps",
"eventType": "outbound_message_status_changed",
"description": "ChatApps outbound message delivery receipt",
"payload": {
"umid": <UNIQUE_MESSAGE_ID>,
"batchId": <BATCH_ID>,
"clientMessageId": <YOUR_MESSAGE_ID>,
"clientBatchId": <YOUR_BATCH_ID>,
"subAccountId": <SUBACCOUNT_ID>,
"channel": "whatsapp",
"user": {
"msisdn": "+6512345678",
"channelUserId": "+6512345678"
},
"status": {
"state": "undelivered",
"detail": "rejected_by_operator",
"timestamp": "2016-01-01T00:00:00Z",
"errorCode": 15,
"errorMessage": "Invalid destination"
}
}
}