Webhook documentation
RCS Business Messaging Webhook Integration
An RCS webhook is the HTTPS callback through which an RCS Business Messaging platform tells your system what happened to a message sent from your verified agent: that it was delivered or read, or that the customer replied or tapped a suggested action.
Updated
How RCS event notifications work
RCS messages are sent from an agent, the verified brand sender shown in the customer’s messaging app. Once a message is sent, the platform can notify your callback URL about two kinds of activity:
- Status events describe your message: submitted, delivered, read or failed.
- User events describe what the customer did: a free-text reply, a tap on a suggested reply, or a tap on a suggested action such as opening a link or dialling a number.
Submitted, delivered and read events
| Event | What it tells you | Caveat |
|---|---|---|
| Submitted | The message was accepted for sending through your agent. | Not a delivery confirmation. |
| Delivered | The message reached an RCS-capable device. | Requires the device to be online and RCS-enabled. |
| Read | The customer opened the message. | Reported only where the platform and device provide read information. |
Delivered and read measure different things. A message can be delivered and never read, and a missing read event is not proof that the customer ignored it.
Failed events and fallback
A failed event means the message could not be delivered over RCS, for example because the recipient’s device or network does not support RCS, or the message expired before the device came online. Record the failure reason and decide whether to send the information another way.
Customer replies
When a customer types a reply to your agent, the platform delivers it as a user event with the text and a reference to the conversation. Route replies to the right place, such as a chatbot, a support queue or a CRM, and treat replies like “STOP” as opt-out requests in line with your consent records.
CTA and suggestion interaction events
Rich cards and carousels can include suggested replies and suggested actions. When you build the message, you attach your own postback data to each suggestion, for example confirm_appointment_8841. When the customer taps it, the event returns that postback data, so your system knows exactly which button on which message was used without parsing text.
- Keep postback values short, unique per action and free of personal data.
- Validate postback values against what you actually sent; ignore unknown values.
- Some actions, such as opening a URL, hand the customer to another app, so a tap event may be the last signal you receive.
Message ID and agent correlation
Store the message ID returned at submission together with the agent that sent it. Brands with separate agents for different services, for example sales and support, need the agent ID to route replies and to report engagement per agent. User events such as replies may reference the conversation or the customer rather than a single message, so keep a conversation record as well as a message record.
Illustrative RCS read event
{
"event_id": "evt_example_002",
"event_type": "message.read",
"message_id": "msg_example_456",
"agent_id": "agent_example_brand",
"channel": "rcs",
"status": "READ",
"timestamp": "2026-11-08T10:32:15Z"
}Compared with an SMS report, this example adds agent_id so the event can be tied to the sending brand agent, and its status is READ, an engagement signal that SMS cannot provide. event_id still identifies this specific notification for deduplication, and timestamp is when the read was recorded.
Event ordering
Status and user events travel independently. A read event can arrive before the delivered event, and a reply can arrive before either. Use timestamps to build the timeline, treat “read” as implying “delivered”, and never downgrade a message from read to delivered because a late event arrived.
Retry handling
Acknowledge each event quickly and process it asynchronously. If your endpoint is slow or returns errors, the same event may be delivered again where retries are supported, so deduplicate on the event ID. The retry behaviour for your account requires confirmation. See the webhook security guide for idempotency and backoff patterns.
Customer engagement reporting
Because RCS reports interactions, you can measure more than delivery:
| Measure | Calculation | Note |
|---|---|---|
| Delivery rate | Delivered ÷ submitted | Excludes devices without RCS |
| Read rate | Read ÷ delivered | A lower bound where read events are not always reported |
| Reply rate | Messages with a reply ÷ delivered | Count conversations, not individual replies |
| Action rate | Suggestion taps ÷ delivered | Report per suggestion using postback data |
RCS onboarding and SMS DLT
RCS onboarding follows its own business verification and agent launch process, described in the RCS Business Messaging registration guide. Webhook configuration is part of the technical setup after your agent is approved.
Frequently asked questions
Which RCS events can I receive by webhook?
Typical events are submitted, delivered, read and failed status events, plus customer replies and suggestion taps. Not every provider supports every event; the events available for your agent are confirmed during onboarding.
Why do some RCS messages show delivered but never read?
Read information is reported only where the platform and device provide it, and the customer may not have opened the message. Treat read rate as a lower bound.
How do I know which button a customer tapped?
Attach unique postback data to each suggested reply or action when you build the message. The interaction event returns that postback data.
Do I need DLT registration to receive RCS webhooks?
No. RCS bot registration is separate from SMS DLT registration, and DLT registration or a PE ID is not required for TXTPro RCS onboarding. DLT applies only if you also send SMS, for example as a fallback.
