Delivery receipts for Outbound Messaging Apps

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. - `outbound_message_status_changed` for delivery receipts - `external_app_message` for WhatsApp Business App messages
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
timestamp	string	UTC date and time when the message was sent expressed in ISO 8601 format. Only present when `eventType=external_app_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
type	string	Message type. See Inbound Messaging Apps message type field for possible values. Only present when `eventType=external_app_message`
content	object	Message content. Structure varies based on the `type` field. Only present when `eventType=external_app_message`
status	object	Current status of the message, please see Message status reference for details. Only present when `eventType=outbound_message_status_changed`
whatsapp	object	WhatsApp-specific information. Only present when `channel` is `whatsapp`. See below 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

WhatsApp object description

Parameter name	Parameter type	Description
providerErrorCode	string	WhatsApp's own error code. Only present if there was an error
pricingCategory	string	WhatsApp's pricing category as defined by Meta. Only included with sent status, and one of either delivered or read status

🚧

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"
    },
    "whatsapp": {
      "pricingCategory": "business_initiated"
    }
  }
}

{
  "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"
    },
    "whatsapp": {
      "pricingCategory": "user_initiated"
    }
  }
}

{
  "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"
    },
    "whatsapp": {
      "providerErrorCode": "131009"
    }
  }
}

WhatsApp Business App Messages

When using WhatsApp with Embedded Signup, messages sent by your business through the WhatsApp Business App are forwarded to your configured webhook as external_app_message events. This allows you to track all outbound messages sent on behalf of your business through the WhatsApp Business App.

📘

For more information, see WhatsApp's Embedded Signup documentation.

Key differences from delivery receipts:

eventType is external_app_message instead of outbound_message_status_changed
Includes timestamp, type, and content fields in the payload (see webhook format above)
Does not include status, batchId, clientMessageId, or clientBatchId fields

Sample WhatsApp Business App message webhook

{
  "namespace": "ChatApps",
  "eventType": "external_app_message",
  "description": "External App Message",
  "payload": {
    "umid": "20a5347f-6898-4f39-86ef-b3e100b50929",
    "subAccountId": "integration_test_whatsapp",
    "timestamp": "2026-01-28T09:16:53.00Z",
    "channel": "whatsapp",
    "user": {
      "msisdn": "+16505551234",
      "channelUserId": "16505551234"
    },
    "type": "Text",
    "content": {
      "text": "Here's the info you requested! https://www.meta.com/quest/quest-3/"
    }
  }
}

Requirements​

Retry logic​

Read Receipt - Validity Period​

Webhook format​

Sample delivery receipt for outbound message​

WhatsApp Business App Messages​

Sample WhatsApp Business App message webhook​