Delivery receipts for outbound SMS

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 nameParameter typeDescription
namespacestringA generic namespace for incoming webhook.
Equal to SMS for delivery receipts.
eventTypestringWebhook type.
Equals to outbound_message_status_changed for delivery receipts.
descriptionstringHuman-readable description of the incoming event
payloadobjectDelivery receipt information, see below.

Payload object description

Parameter nameParameter typeDescription
umiduuidA unique identifier generated by 8x8 for the message
batchIduuidA unique identifier generated by 8x8 for the message if sent using Batch API
clientMessageIdstringYour custom identifier for the message
clientBatchIdstringClient managed id for this batch of messages : your own unique reference
subAccountIdstringThe sub-account id used to deliver the message
sourcestringThe source (i.e: sender) used to deliver the message
destinationstringDestination phone number where the SMS was sent (E.164 format)
statusobjectCurrent status of the message, please see Message status reference for details.
priceobjectPrice information of the message, this field is optional in the response if there is no charge incurred. Please see Price object reference for details
smsCountintegerNumber 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>