RCS Delivery Receipt (DR) Callback Events

The RCS Delivery Receipt Callback Events provide real-time updates on the status of messages sent via the RCS messaging protocol. These events are essential for tracking the lifecycle of a message, from submission to reading by the recipient.

This section outlines the types of DR callback events, their significance, and the structure of the payloads returned by the API.

Callback Types

Each DR callback types includes a 'type' field that indicates the current status of the message. The following types are supported:

Type	Description
`SENT`	Message successfully submitted from Google to the carrier.
`DELIVERED`	Message successfully delivered to the recipient's handset.
`READ`	Message has been read on the recipient's handset.
`ERROR`	Message was undelivered due to an error. Note: The "Callback Error Codes" along with the description, and reason, will be provided in the future update.

Sample Payloads

Each DR event payload is a JSON object containing metadata about the message and its delivery status.

SENT callback:

{ 
  "type": "SENT", 
  "eventId": "c8c3aa5d-1082-45a9-9f88-026c99XXXXX8", 
  "from": "91767XXXXXX3", 
  "to": "mmx_traffic", 
  "sentAt": "2025-06-16T13:46:38.929Z", 
  "messageId": "4543932d-c8f0-48c4-90bf-f9aXXXXXX005" 
  "ref":"child-reference-1",
  "ref1":"child-reference-2",
  "ref2":"child-reference-3"
}

📘
Note:
The "to" parameter is the agent service code.

DELIVERED Callback:

{ 
  "type": "DELIVERED", 
  "eventId": "MxfdhMDmfQQSqKCtBXXXXXlr", 
  "from": "9176XXXXXXXX", 
  "to": "mmx_traffic", 
  "sentAt": "2025-06-16T13:46:41.295Z", 
  "messageId": "4543932d-c8f0-48c4-90bf-f9aXXXXX0056" 
  "ref":"child-reference-1",
  "ref1":"child-reference-2",
  "ref2":"child-reference-3"
}

READ Callback:

{ 
  "type": "READ", 
  "eventId": "MxZJragNjfT=qY4YXXXXX5cA", 
  "from": "9176XXXXXXXX", 
  "to": "mmx_traffic", 
  "sentAt": "2025-06-16T13:46:49.193Z", 
  "messageId": "4543932d-c8f0-48c4-90bf-f9aXXXXX005f" 
  "ref":"child-reference-1",
  "ref1":"child-reference-2",
  "ref2":"child-reference-3"
}

TTL Expired

{
  "type": "TTL_EXPIRATION_REVOKED",
  "eventId": "+9176739XXXXX08652/f58-f739-446a-b1f1-5cXXXXX9d2e6",
  "from": "9176XXXXX732",
  "to": "QA_Sanity_Stage",
  "sentAt": "2026-01-13T09:58:49.970Z",
  "messageId": "7942468f-7b22-4aeb-91c3-694XXXXXa696"
  "ref":"child-reference-1",
  "ref1":"child-reference-2",
  "ref2":"child-reference-3"
}

Field Descriptions

The following list contains the field description for delivery receipts:

Field	Type	Description
`type`	String	Status of the message (SENT, DELIVERED, READ, ERROR).
`eventId`	String	Unique identifier for the delivery event.
`from`	String	Sender's identifier (usually a phone number). Sender is the recipient's mobile number to which messages have been sent.
`to`	String	Recipient or service identifier. `to` is a service code and it can be alphanumeric/numeric/long number/short number/special characters.
`sentAt`	String	ISO 8601 timestamp indicating when the event occurred.
`messageId`	String	Unique identifier for the message being tracked.

Message Lifecycle Example

A typical message lifecycle may include the following sequence of events:

SENT → Message submitted to carrier.
DELIVERED → Message delivered to recipient's device.
READ → Message opened/read by recipient.

If delivery fails, an ERROR event may be triggered instead of a DELIVERED event.

Updated 10 days ago