Delivery receipts for outbound Chat Apps

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 nameParameter typeDescription
namespacestringA generic namespace for incoming webhook.
Equal to ChatApps 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
channelstringName of the channel used to send the message, please see List of supported ChatApps channels for details.
userobjectInformation about the user the message is associated with.
statusobjectCurrent status of the message, please see Message status reference for details.
priceobjectPrice information of the message, please see Price object reference for details

User information object description

Parameter nameParameter typeDescription
msisdnstringPhone number expressed in E.164 international format.
channelUserIdstringChannel user identifier.

🚧

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 Failed/Undelivered 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 WhatsApp

{
  "namespace": "ChatApps",
  "eventType": "outbound_message_status_changed",
  "description": "ChatApps Outbound Message Delivery Receipt",
  "payload": {
    "umid": "5ef3c9ae-18d7-425a-a518-329de6f43d03",
    "batchId": "95f8bc5e-7517-eb11-815c-022a22cc1c71",
    "clientMessageId": "cde4ef5e-7517-eb11-8278-00155d9f27ac",
    "clientBatchId": "f38ea8a7-7517-eb11-827b-00155d7d21a4",
    "subAccountId": "TestSubAccountId",
    "channel": "whatsapp",
    "user": {
      "msisdn": "+6581968289",
      "channelUserId": "+6581968289"
    },
    "status": {
      "state": "undelivered",
      "detail": "rejected_by_operator",
      "timestamp": "2016-01-01T00:00:00Z",
      "errorCode": 15,
      "errorMessage": "Invalid destination"
    },
    "price": {
      "total": 3.0375,
      "currency": "IDR"
    },
  }
}