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 type includes a 'type' field that indicates which type of event the Delivery Receipt refers to. 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.
`COMPOSING`	Recipient has started composing a reply.
`TTL_EXPIRATION_REVOKED`	Message expired due to TTL before delivery and was revoked.
`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.

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 is the recipient's mobile number to which messages have been sent.
`to`	String	To represent the RCS Agent Service Code that was used to process the request to send an RCS MT message. 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 to which the event refers to.
`carrierId`	String	Identifier of the carrier or network operator responsible for delivering the message.

Sample Payloads

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

SENT callback:

{
  "code": "4000",
  "message": "Message successfully submitted to the carrier",
  "data": {
    "type": "SENT",
    "eventId": "81500376-6398-4301-8d51-de4720XXXXX9",
    "from": "19XXXXXXXXX",
    "to": "kio_rcs",
    "sentAt": "2026-04-16T17:08:23.992Z",
    "messageId": "db8ff102-fe16-4d79-a682-fXXXXXb3fe07",
    "carrierId": "VZ"
  },
  "error": {}
}

📘
Note:
The "to" parameter is the RCS Agent (that was used to send the RCS MT message) service code.

SENT Callback including optional Ref parameters

📘
Note:
If the initial RCS API request to send an MT message includes the optional Ref parameters, see Ref parameters in Send a Plain Text Message API for details. These parameters are also returned in the callback payload for reference.

{
  "code": "2000",
  "message": "Message successfully submitted to the carrier",
  "data": {
    "type": "SENT",
    "eventId": "b38bb617-b1b2-4d33-8746-XXXXXXXX264c",
    "from": "17XXXXXXXXX",
    "to": "kio_rcs",
    "sentAt": "2026-04-16T13:46:05.845Z",
    "messageId": "ce976c3b-8373-411c-9b02-8eXXXXXXXXfc",
    "ref": "test",
    "ref1": "test1",
    "ref2": "test2",
    "carrierId": "ATT"
  },
  "error": {}
}

DELIVERED Callback:

{
  "code": "4001",
  "message": "Message successfully delivered to the end user",
  "data": {
    "type": "DELIVERED",
    "eventId": "Mx0YTsHP3NSPXXXXXXXXWSRw",
    "from": "19XXXXXXXXX",
    "to": "kio_rcs",
    "sentAt": "2026-04-16T17:08:25.519Z",
    "messageId": "db8ff102-fe16-4d79-a682-fb38XXXXX307",
    "carrierId": "VZ"
  },
  "error": {}
}

DELIVERED callback with additional optional Ref parameters

📘
Note:
If the initial RCS API request to send an MT message includes the optional Ref parameters, see Ref parameters in Send a Plain Text Message API for details. These parameters are also returned in the callback payload for reference.

{
  "code": "2001",
  "message": "Message successfully delivered to the end user",
  "data": {
    "type": "DELIVERED",
    "eventId": "MxSJWCUA6NSXXXXXXXXpm3XQ",
    "from": "17XXXXXXXXX",
    "to": "kio_rcs",
    "sentAt": "2026-04-16T13:46:06.303Z",
    "messageId": "ce976c3b-8373-411c-9b02-8eXXXXXXXXfc",
    "ref": "test",
    "ref1": "test1",
    "ref2": "test2",
    "carrierId": "ATT"
  },
  "error": {}
}

READ Callback:

{
  "code": "4002",
  "message": "Message read confirmation received",
  "data": {
    "type": "READ",
    "eventId": "MxM8b9hRVtS=emYHXXXXXXXX",
    "from": "19XXXXXXXXX",
    "to": "kio_rcs",
    "sentAt": "2026-04-16T17:08:32.318Z",
    "messageId": "db8ff102-fe16-4d79-a682-fbXXXXXXXX37",
    "carrierId": "VZ"
  },
  "error": {}
}

READ Callback with additional optional Ref parameters

📘
Note:
If the initial RCS API request to send an MT message includes the optional Ref parameters, see Ref parameters in Send a Plain Text Message API for details. These parameters are also returned in the callback payload for reference.

{
  "code": "2002",
  "message": "Message read confirmation received",
  "data": {
    "type": "READ",
    "eventId": "MXXXXXXXXxa=mmx9SDfMaJVA",
    "from": "17XXXXXXXXX",
    "to": "kio_rcs",
    "sentAt": "2026-04-16T13:55:33.034Z",
    "messageId": "ce976c3b-8373-411c-9b02-8eXXXXXXXXXc",
    "ref": "test",
    "ref1": "test1",
    "ref2": "test2",
    "carrierId": "ATT"
  },
  "error": {}
}

TTL_EXPIRATION_REVOKED

{
  "code": "4004",
  "message": "Message TTL expiration revoked by the carrier",
  "data": {
    "type": "TTL_EXPIRATION_REVOKED",
    "eventId": "MXXXXXXXXxa=mmx9SDfMaJVA",
    "from": "19XXXXXXXXX",
    "to": "kio_rcs",
    "sentAt": "2026-04-16T17:08:51.650Z",
    "messageId": "08d060d0-2392-4efd-a7c2-e6cXXXXX604e",
    "carrierId": "VZ"
  },
  "error": {}
}

INTERNAL ERROR

{
  "code": "2101",
  "message": "Rcs INTERNAL_ERROR",
  "data": {
    "type": "ERROR",
    "eventId": "c4509648-1e51-43a0-ad08-dXXXXXXXXee3",
    "from": "17XXXXXXXX8",
    "to": "US_prod_1",
    "sentAt": "2026-04-16T13:33:04.741Z",
    "messageId": "597f7d13-21fa-419e-9739-fXXXXXXXX9bf",
    "carrierId": "ATT"
  },
  "error": {
    "error_code": "INTERNAL_ERROR",
    "error_message": "com.mgage.XXXX.rcsi.service.integration.atnt.ApiException: Unauthorized"
  }
}

THIS OPERATION IS BLOCKED

{
  "code": "3101",
  "message": "This operation is blocked",
  "data": {
    "type": "ERROR",
    "eventId": "1db6f7c5-cb70-49b5-ba92-cXXXXXXXXXee",
    "from": "13XXXXXXXXX",
    "to": "rcs_stage_04",
    "sentAt": "2026-04-10T06:47:40.509Z",
    "messageId": "3434a1ab-a467-4ec7-80f0-2761XXXXX01e",
    "carrierId": "TMO",
  },
  "error": {
    "error_code": "CARRIER_ERROR",
    "error_message": "This operation is blocked",
  }
}

UNKNOWN DEVICE OR RCS CAPABILITIES UNKNOWN FOR NUMBER

{
  "code": "9101",
  "message": "Unknown device or RCS capabilities unknown for number",
  "data": {
    "type": "ERROR",
    "eventId": "f3eae9e4-2ed0-4ba1-9c10-abXXXXXXXXb8",
    "from": "17XXXXXXXXX",
    "to": "rcs_stage_05",
    "sentAt": "2026-04-13T09:14:47.789Z",
    "messageId": "4e754be8-2526-485f-906d-22XXXXXXXXX4",
    "carrierId": "",
  },
  "error": {
    "error_code": "RCS_UNKNOWN",
    "error_message": "Unknown device or RCS capabilities unknown for number",
  }
}

Agent not provisioned or lacks permission for the service or MSISDN not found or destination is not an AT&T subscriber

{
  "code": "2101",
  "message": "Agent not provisioned or lacks permission for the service or MSISDN not found or destination is not an AT&T subscriber",
  "data": {
    "type": "ERROR",
    "eventId": "ee10bcb3-8e42-4f8e-9910-XXXXXXXX042b",
    "from": "17XXXXXXXXX",
    "to": "rcs_stage_05",
    "sentAt": "2026-04-13T09:21:47.705Z",
    "messageId": "ed8e107e-746a-4683-a021-bbXXXXXXXXa0",
    "carrierId": "ATT",
  },
  "error": {
    "error_code": "INTERNAL_ERROR",
    "error_message": "Agent not provisioned or lacks permission for the service or MSISDN not found or destination is not an AT&T subscriber",
  }
}

NO PROVIDER FOUND FOR SERVICE CODE

{
  "code": "4101",
  "message": "Rcs NO_ROUTE",
  "data": {
    "type": "ERROR",
    "eventId": "9688119a-88a8-407f-b72e-3XXXXXXXXec7",
    "from": "19XXXXXXXXX",
    "to": "rcs_stage_05",
    "sentAt": "2026-04-13T09:09:03.173Z",
    "messageId": "79298f27-1e52-4013-a466-c62XXXXXXXX6",
    "carrierId": "VZ",
  },
  "error": {
    "error_code": "NO_ROUTE",
    "error_message": "No provider found for service code: rcs_stage_05",
  }
}

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.

Event Code Mapping by Carrier:

Event	ATT	TMOB	Verizon	VI	JIO	Default
SENT	2000	3000	4000	5000	6000	9000
DELIVERED	2001	3001	4001	5001	6001	9001
READ	2002	3002	4002	5002	6002	9002
COMPOSING	2003	3003	4003	5003	6003	9003
TTL_EXPIRATION_REVOKED	2004	3004	4004	5004	6004	9004
SUBSCRIBE	2005	3005	4005	5005	6005	9005
UNSUBSCRIBE	2006	3006	4006	5006	6006	9006
USER_MESSAGE	2007	3007	4007	5007	6007	9007
ERROR CODE	2101	3101	4101	5101	6101	9101

Sample Error Response:

{
  "code": "5101",
  "message": "This operation is blocked",
  "data": {
    "type": "ERROR",
    "eventId": "9e2e1c8e-1a4e-49da-9211-4572XXXXXf37",
    "from": "91XXXXXXXXXX",
    "to": "rcs-viTCLstage",
    "sentAt": "2026-04-20T05:47:14.324Z",
    "messageId": "55c81380-15b7-43d8-b742-a29XXXXX1eff",
    "carrierId": "VI"
  },
  "error": {
    "error_code": "CARRIER_ERROR",
    "error_message": "401-D:User is not in conversation and provided message is not a template"
  }
}

Refer to the following table for error messages in India:

Error Code	Error Message
402	Insufficient balance. Please recharge to send message.
450	Bot blocked for spam.
409	User is not in a conversation and provided message template is not approved.
410	Opted out.
423	DND enabled.
429	Monthly message limit exceeded.
404	Number is RCS disabled.
429G	Too many requests: request limit exceeded.
502	Unable to charge for this message.
500	Internal server error.
400	MaaP specific error.
400A	Template provided with insufficient custom params.
403	Invalid ClientID/IP.
0	Unknown error.
400-A	Template provided with insufficient params.
400-B	Template not approved.
400-C	Test template limit exceeded.
400-D	Template code with bot does not exist.
400-E	Agent not found.
400-F	Not a valid JSON message.
400-G	Message type not supported.
400-H	Invalid phone number.
400-MOI	MaaP specific error (Google).
401-A	Unauthorized.
401-B	Invalid Client ID.
401-C	Invalid IP address.
401-D	User not in conversation and message is not a template.
402-A	Low balance: Please recharge.
403-A	Bot not launched.
403-B	User opted out.
403-C	Bot blocked for spam.
404-A	RCS disabled.
409-MOI	MaaP specific error (Google).
429-A	Too many requests.
429-B	Monthly message limit exceeded.
429-MOI	MaaP specific error (Google).
500-A	Internal server error.
502-A	Bad gateway.
502-MOI	Timeout from downstream MaaP (Google).
503-A	Curfew hours.
504-A	Timeout.
400-M14	MaaP specific error.
409-M14	MaaP specific error.
429-M14	MaaP specific error.
502-M14	Timeout from downstream MaaP.
423-A	DND enabled.
500-B	Unable to charge for this message.
403-D	Agent suspended.
429-B-MOI	Traffic limit reached for agent on distinct users.
404-B	Operation blocked – DND enabled.
429-C-MOI	Recipient daily promotional message quota exceeded.

Updated about 4 hours ago