Delivery Receipts (DR) are webhooks for delivery statuses: POST
requests sent by 8x8 platform in JSON
format to the delivery reports callback URL configured for your account.
Whenever a message has a new delivery status associated with the delivery stage it is in, 8x8 sends out a POST
request with the new status to the callback URL.
You can configure your callback using Webhooks Configuration API
You can also overwrite the default callback URL on a per-message / per-batch-of-message basis by specifying a different dlrCallbackUrl
value in your API requests when sending a message or a batch of messages (see Send 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.
Delivery Receipt - Validity Period
If we do not receive a delivery receipt from the SMS carrier promptly, our platform will continue checking for up to 48 hours for a delivery receipt. If the delivery receipt is received after this 48-hour period, there will be no delivery receipt webhook sent.
Webhook format
Request body description
Parameter name | Parameter type | Description |
---|---|---|
namespace | string | A generic namespace for incoming webhook. Equal to SMS 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 | Your custom identifier for the message |
clientBatchId | string | Client managed id for this batch of messages : your own unique reference |
subAccountId | string | The sub-account id used to deliver the message |
source | string | The source (i.e: sender) used to deliver the message |
destination | string | Destination phone number where the SMS was sent (E.164 format) |
status | object | Current status of the message, please see Message status reference for details. |
price | object | Price information of the message, this field is optional in the response if there is no charge incurred. Please see Price object reference for details |
smsCount | integer | Number of SMS segment in the message |
Please note that the Price object is optional and might not be included in the Delivery Receipts callback. When a message was not sent successfully, you will still receive Delivery Receipts with Rejected status without incurring any charges. Hence, the price information is not available for the Delivery Receipts.
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 SMS
{
"namespace": "SMS",
"eventType": "outbound_message_status_changed",
"description": "SMS outbound message delivery receipt",
"payload": {
"umid": "9e09ac86-bd74-5465-851d-1eb5a5fdbb9a",
"batchId": "3e09ac86-bd74-5465-851d-1eb5a5fdbb9b",
"clientMessageId": "1e09ac86-bd74-5465-851d-1eb5a5fdbb9b",
"clientBatchId": "2e09ac86-bd74-5465-851d-1eb5a5fdbb9b",
"subAccountId": "SubAccount-1",
"source": "8x8",
"destination": "+12025550293",
"status": {
"state": "undelivered",
"detail": "rejected_by_operator",
"timestamp": "2016-01-01T00:00:00Z",
"errorCode": 15,
"errorMessage": "Invalid destination"
},
"price": {
"total": 0.0375,
"perSms": 0.0125,
"currency": "USD"
},
"smsCount": 3
}
}
<?xml version="1.0" encoding="UTF-8" ?>
<root>
<namespace>SMS</namespace>
<eventType>outbound_message_status_changed</eventType>
<description>SMS outbound message delivery receipt</description>
<payload>
<umid>9e09ac86-bd74-5465-851d-1eb5a5fdbb9a</umid>
<batchId>3e09ac86-bd74-5465-851d-1eb5a5fdbb9b</batchId>
<clientMessageId>1e09ac86-bd74-5465-851d-1eb5a5fdbb9b</clientMessageId>
<clientBatchId>2e09ac86-bd74-5465-851d-1eb5a5fdbb9b</clientBatchId>
<subAccountId>SubAccount-1</subAccountId>
<source>8x8</source>
<destination>+12025550293</destination>
<status>
<state>undelivered</state>
<detail>rejected_by_operator</detail>
<timestamp>2016-01-01T00:00:00Z</timestamp>
<errorCode>15</errorCode>
<errorMessage>Invalid destination</errorMessage>
</status>
<price>
<total>0.0375</total>
<perSms>0.0125</perSms>
<currency>USD</currency>
</price>
<smsCount>3</smsCount>
</payload>
</root>