Skip to main content
GuidesAPI ReferenceSupport

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​

📘

If you are still receiving webhooks in an older format, see the Webhook migration guide for help migrating your configuration.

Request body description

Parameter nameParameter typeDescription
versionintegerNew in v9. Version of the webhook payload format. Equals to 9 for this format.
namespacestringA generic namespace for incoming webhook.
Equal to ChatApps for delivery receipts.
eventTypestringWebhook type.
- outbound_message_status_changed for delivery receipts
- external_app_message for WhatsApp Business App messages
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
clientMessageIdstringCustom identifier you provided for this message
clientBatchIdstringCustom identifier you provided for this batch of messages
subAccountIdstringThe sub-account id used to deliver the message
timestampstringUTC date and time when the message was sent expressed in ISO 8601 format.
Only present when eventType=external_app_message
channelstringName of the channel used to send the message, please see List of supported Messaging Apps channels for details
userobjectInformation about the user the message is associated with
typestringMessage type. See Inbound Messaging Apps message type field for possible values.
Only present when eventType=external_app_message
contentobjectMessage content. Structure varies based on the type field.
Only present when eventType=external_app_message
statusobjectCurrent status of the message, please see Message status reference for details.
Only present when eventType=outbound_message_status_changed
whatsappobjectWhatsApp-specific information. Only present when channel is whatsapp. See below for details
outboundContentobjectNew in v9. A structured copy of the original outbound message this receipt refers to. WhatsApp only, and only present on the receipt that carries the delivered content (the delivered_to_recipient status). See outboundContent object below.

User information object description

Parameter nameParameter typeDescription
msisdnstringChanged in v9. The recipient phone number expressed in E.164 international format. Left out for channels where users have no phone number (e.g. LINE).
channelUserIdstringChanged in v9. The user's id on the channel: the BSUID (business-scoped user id) for WhatsApp, or the Line user id for Line. Only included when the channel provides a real user id.

When a user field has no value, it is simply left out of the JSON.

⚠️ When channelUserId is missing (WhatsApp only)

channelUserId is only present in the receipts reported by WhatsApp itself. When the message is sent with a phone number as the destination, the queued and delivered_to_operator receipts — generated before the message reaches WhatsApp — will not contain channelUserId, while the delivered_to_recipient and read receipts will include it.

WhatsApp object description

Parameter nameParameter typeDescription
providerErrorCodestringWhatsApp's own error code. Only present if there was an error
pricingCategorystringWhatsApp'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.

outboundContent object​

outboundContent is a structured, channel-normalized copy of the message you originally sent. It lets you reconcile a delivery receipt with the exact content that was delivered without keeping your own copy of the outbound payload.

📘

outboundContent is WhatsApp only. It is attached to the receipt that confirms delivery to the recipient (delivered_to_recipient) and is omitted from earlier receipts such as queued and delivered_to_operator. When the content cannot be reconstructed it is left out entirely.

Parameter nameParameter typeDescription
channelstringChannel the content was sent on. Always whatsapp.
contentTypestringKind of content. See contentType values below.
templateobjectTemplate metadata. Only present when contentType is template, template_auth, or carousel.
headerobjectMessage header (text, media, or location). Omitted when the message has no header, and for carousel (per-card headers are used instead).
bodyobjectMessage body text.
footerobjectMessage footer text.
actionsobjectInteractive elements (buttons, call-to-action, list, or flow). Omitted for carousel (per-card actions are used instead).
cardsarrayCarousel cards, in order. Only present when contentType is carousel.
metaobjectExtra flags such as redaction status and interactive sub-type.
contentType values​
ValueDescription
textFreeform text message.
mediaFreeform image, video, audio, or document. The media type is carried in header.type.
locationFreeform location message.
templateStandard (non-authentication) template message.
template_authAuthentication template. Its one-time code is redacted — see Redaction below.
carouselCarousel template. Content is carried per card in the cards array.
interactiveInteractive message (quick-reply buttons, list, call-to-action URL, or flow). The sub-type is in meta.interactiveType.
header object​
Parameter nameParameter typeDescription
typestringOne of text, image, video, audio, document, or location.
textstringHeader text. Only present when type is text.
mediaobjectMedia descriptor. Only present for image, video, audio, and document headers. Contains url, and filename for documents.
locationobjectLocation descriptor (latitude, longitude, and optionally name and address). Only present when type is location.
body / footer objects​
Parameter nameParameter typeDescription
textstringThe body or footer text.
actions object​
Parameter nameParameter typeDescription
buttonsarrayButtons, in order. Each has type (url, quick_reply, copy_code, phone, or flow), label, and value (null for buttons that carry no value, such as quick_reply).
ctaobjectCall-to-action URL button (displayText, url).
listobjectList picker: buttonLabel plus sections, each with an optional title and a rows array (id, title, optional description).
flowobjectWhatsApp Flow details (flowId, cta, action, screen).

Each entry has an index (zero-based position) and its own header, body, and actions, structured exactly as above.

meta object​
Parameter nameParameter typeDescription
redactedbooleantrue when part of the content was masked.
redactionReasonstringWhy the content was masked.
interactiveTypestringSub-type of an interactive message: button, list, cta_url, or flow.
Redaction​

Some content is masked before it reaches your webhook, in which case meta.redacted is true:

  • Authentication templates (contentType is template_auth): the one-time code is replaced with ****** in the body and in any copy-code button. meta.redactionReason is OTP codes are masked in agent-facing contexts.
  • PII masking (when enabled on your sub-account): the content is withheld, leaving only channel, contentType, and meta. meta.redactionReason is Content masked for PII compliance.

Sample payloads​

WhatsApp — queued​

Sent when the message is accepted by the 8x8 platform. In this example the message was sent using the phone number (msisdn); since this status does not come back from WhatsApp, channelUserId is not included.

Outbound delivery receipt webhook body (v9) — WhatsApp, queued
{
  "version": 9,
  "namespace": "ChatApps",
  "eventType": "outbound_message_status_changed",
  "description": "ChatApps outbound message delivery receipt",
  "payload": {
    "umid": <UNIQUE_MESSAGE_ID>,
    "subAccountId": <SUBACCOUNT_ID>,
    "channel": "whatsapp",
    "user": {
      "msisdn": <USER_PHONE_NUMBER>
    },
    "status": {
      "state": "queued",
      "timestamp": "2026-07-03T03:23:21.90Z"
    }
  }
}
WhatsApp — delivered to recipient​

This receipt comes back from WhatsApp, so the user object includes the new channelUserId (BSUID). The delivered_to_recipient receipt also carries the outboundContent object — a structured copy of the message that was delivered. The examples below show the receipt for different content types; only the outboundContent object varies, the surrounding webhook body is the same in each case.

Outbound delivery receipt webhook body (v9) — WhatsApp, delivered, freeform text
{
  "version": 9,
  "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": <USER_PHONE_NUMBER>,
      "channelUserId": <WHATSAPP_BSUID>
    },
    "status": {
      "state": "delivered",
      "detail": "delivered_to_recipient",
      "timestamp": "2026-07-03T03:40:54.16Z"
    },
    "whatsapp": {
      "pricingCategory": "marketing"
    },
    "outboundContent": {
      "channel": "whatsapp",
      "contentType": "text",
      "body": {
        "text": "Welcome to 8x8 Inc.! We are the leading global provider of unified cloud communications, video collaboration, and contact center solutions."
      }
    }
  }
}

Template with an image header, a URL button, and a quick-reply button:

Outbound delivery receipt webhook body (v9) — WhatsApp, delivered, template
{
  "version": 9,
  "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": <USER_PHONE_NUMBER>,
      "channelUserId": <WHATSAPP_BSUID>
    },
    "status": {
      "state": "delivered",
      "detail": "delivered_to_recipient",
      "timestamp": "2026-07-03T03:40:54.16Z"
    },
    "whatsapp": {
      "pricingCategory": "marketing"
    },
    "outboundContent": {
      "channel": "whatsapp",
      "contentType": "template",
      "template": {
        "name": "marketing_welcome_template",
        "language": "en_US",
        "category": "MARKETING"
      },
      "header": {
        "type": "image",
        "media": {
          "url": "<HEADER_IMAGE_URL>"
        }
      },
      "body": {
        "text": "Hi Jason, ready to elevate your customer communications? Discover the power of 8x8 CPaaS."
      },
      "footer": {
        "text": "Powered by 8x8"
      },
      "actions": {
        "buttons": [
          {
            "type": "url",
            "label": "Discover all channels",
            "value": "https://cpaas.8x8.com/en/products/omnichannel-messaging"
          },
          {
            "type": "quick_reply",
            "label": "Talk to Sales",
            "value": null
          }
        ]
      }
    }
  }
}

Interactive list message (note meta.interactiveType):

Outbound delivery receipt webhook body (v9) — WhatsApp, delivered, interactive list
{
  "version": 9,
  "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": <USER_PHONE_NUMBER>,
      "channelUserId": <WHATSAPP_BSUID>
    },
    "status": {
      "state": "delivered",
      "detail": "delivered_to_recipient",
      "timestamp": "2026-07-03T03:40:54.16Z"
    },
    "whatsapp": {
      "pricingCategory": "marketing"
    },
    "outboundContent": {
      "channel": "whatsapp",
      "contentType": "interactive",
      "header": {
        "type": "text",
        "text": "8x8 Customer Success personalized sessions"
      },
      "body": {
        "text": "Looking for personalized assistance? Our Customer Success team has the following slots available. Tap to select a time."
      },
      "footer": {
        "text": "For urgent inquiries, email cpaas-sales@8x8.com"
      },
      "actions": {
        "list": {
          "buttonLabel": "Book Slot",
          "sections": [
            {
              "title": "Oct 9, 2024",
              "rows": [
                { "id": "slot-1", "title": "Monday, Oct 9", "description": "9:00 AM - 10:00 AM" },
                { "id": "slot-2", "title": "Monday, Oct 9", "description": "2:00 PM - 3:00 PM" }
              ]
            }
          ]
        }
      },
      "meta": {
        "interactiveType": "list"
      }
    }
  }
}
WhatsApp — read recipient​

This receipt also comes back from WhatsApp, so the user object includes channelUserId.

Outbound delivery receipt webhook body (v9) — WhatsApp, read
{
  "version": 9,
  "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": <USER_PHONE_NUMBER>,
      "channelUserId": <WHATSAPP_BSUID>
    },
    "status": {
      "state": "read",
      "timestamp": "2026-07-03T05:12:41.30Z"
    },
    "whatsapp": {
      "pricingCategory": "marketing"
    }
  }
}
Viber — delivered to recipient​

For Viber and RCS there is no channelUserId: these channels identify the recipient purely by phone number, so only user.msisdn is sent.

Outbound delivery receipt webhook body (v9) — Viber, delivered
{
  "version": 9,
  "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": "viber",
    "user": {
      "msisdn": <USER_PHONE_NUMBER>
    },
    "status": {
      "state": "delivered",
      "detail": "delivered_to_operator",
      "timestamp": "2026-07-03T03:21:26.06Z"
    }
  }
}
RCS — read receipt​
Outbound delivery receipt webhook body (v9) — RCS, read
{
  "version": 9,
  "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": "rcs",
    "user": {
      "msisdn": <USER_PHONE_NUMBER>
    },
    "status": {
      "state": "read",
      "timestamp": "2026-07-03T03:41:51.85Z"
    }
  }
}

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​
WhatsApp Business App message webhook body (v9)
{
  "version": 9,
  "namespace": "ChatApps",
  "eventType": "external_app_message",
  "description": "External App Message",
  "payload": {
    "umid": <UNIQUE_MESSAGE_ID>,
    "subAccountId": <SUBACCOUNT_ID>,
    "timestamp": "2026-01-28T09:16:53.00Z",
    "channel": "whatsapp",
    "user": {
      "msisdn": <USER_PHONE_NUMBER>,
      "channelUserId": <WHATSAPP_BSUID>
    },
    "type": "Text",
    "content": {
      "text": "Here's the info you requested! https://www.meta.com/quest/quest-3/"
    }
  }
}