Delivery Report (DR) are webhooks for Chat 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 inbound Chat Apps capabilities, you need:
- An account configured to use Chat 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 48 hours. If the user reads the message after this 48-hour 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 ChatApps 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"
}
}
}