Webhooks for Transactional RCS

Transactional RCS webhook events enable you to track the delivery status of messages sent through the Transactional RCS API. To receive these events, specify your webhook endpoint in the callback field of the /rcs/v1/send request.

Set up a Webhook

Transactional RCS uses the same callback mechanism as Transactional SMS. Add the callback field to the request body of your /rcs/v1/send request. Insider One sends webhook events to this URL as HTTP POST requests.

{
    "callback": "https://yourdomain/9c99bc26-373e-4847-b725-d7103803c111"
}

The callback value must be a valid URL. Once it is set, Insider One sends the RCS delivery status events (RCS Delivered, RCS Undelivered, and RCS Failed) to this URL in real time.

You can also add uniqueArgs to the payload. Any key-value pairs you pass in uniqueArgs are echoed back unchanged in every callback, so you can use them to match incoming events to your own records.

Each webhook event includes the following information:

• id: The message identifier that matches the messageId or messageSid returned in the API response.

• phoneNumber: The recipient's phone number.

• uniqueArgs: The tracking arguments provided in the original API request.

• event: The name of the webhook event.

• channel: The messaging channel. The channel field is always set to rcs so you can distinguish RCS events from SMS events.

• timestamp: The Unix timestamp indicating when the event occurred.

Failure and undelivered events might also include a reason object that explains why the message could not be delivered.

RCS Delivered

The txn_rcs_delivered event indicates that the RCS message was successfully delivered to the recipient's device.

{
  "id": "rcs-a1b2c3d4e5f6a7b8c9",
  "phoneNumber": "+905555555555",
  "uniqueArgs": {
    "orderId": "12345"
  },
  "event": "txn_rcs_delivered",
  "channel": "rcs",
  "timestamp": 1234567890
}

RCS Undelivered

The txn_rcs_undelivered event indicates that the RCS message could not be delivered to the recipient.

If SMS fallback is enabled and the delivery failure is eligible for fallback, Insider One automatically sends the fallback SMS. You, then receive the corresponding standard Transactional SMS callback events for the fallback message in addition to the txn_rcs_undelivered event.

{
  "id": "rcs-a1b2c3d4e5f6a7b8c9",
  "phoneNumber": "+905555555555",
  "uniqueArgs": {
    "orderId": "12345"
  },
  "event": "txn_rcs_undelivered",
  "reason": {
    "message": "RCS Not Supported",
    "code": 5999
  },
  "channel": "rcs",
  "timestamp": 1234567890
}

Undelivered reason codes

The reason.message field contains the reason group mapped from the delivery report received from the RCS provider.

Both reasons are classified as undelivered and are reported through the txn_rcs_undelivered event.

RCS Failed

The txn_rcs_failed event is returned when the outbound delivery report has a status that is neither delivered or seen nor recognized as an undelivered status.

Standard non-delivery cases, such as a recipient whose device does not support RCS, are reported as txn_rcs_undelivered rather than txn_rcs_failed.

{
  "id": "rcs-a1b2c3d4e5f6a7b8c9",
  "phoneNumber": "+905555555555",
  "uniqueArgs": {
    "orderId": "12345"
  },
  "event": "txn_rcs_failed",
  "channel": "rcs",
  "timestamp": 1234567890
}

The reason object is included only when the provider returns a non-zero reason code. It may be omitted when the delivery report contains a failed status without an accompanying reason code.

Event payload fields

Read and seen statuses are collected for reporting and analytics only. They are not sent as webhook events.

Your callback endpoint should respond with an HTTP status code between 200 and 300 to confirm that the event was received successfully.

If the endpoint returns a response outside this range or does not respond, Insider One retries the callback request using the same retry policy as Transactional SMS callbacks.