Send Transactional Single RCS Message

The Transactional RCS API lets you send individually triggered RCS (Rich Communication Services) messages, such as order confirmations, shipping updates, appointment reminders, and account notifications. It supports both text and rich media messages, with optional automatic SMS fallback when a recipient can't receive RCS.

Use this API when messages should be sent immediately after a specific event in your system, rather than through a campaign.

You can send two types of Transactional RCS messages:

• Text

• Rich media (including rich cards and carousels)

Quick-reply buttons are unavailable for Transactional RCS; only static CTA buttons (none or cta) are supported.

To send Transactional RCS messages, Transactional RCS must be enabled for your panel. Otherwise, API requests return a 403 Forbidden response with the message “Transactional RCS messaging is disabled”. Contact the Insider One team to have it enabled.

Refer to Webhooks for Transactional RCS to configure a callback URL if you want to receive delivery events.

Common Use Cases

You can send transactional RCS messages for:

• Order confirmation/information, with a rich card showing a product image and an "Open" CTA

• Shipping and delivery updates

• Appointment confirmations and reminders

• Recurring billing/payment updates

• Welcome messages

• System notifications and account alerts

Since RCS supports rich media, a transactional message can include a branded card with a header image, title, description, and up to four CTA buttons (open URL, dial phone), or a carousel of up to six cards.

How does it work?

1. You submit a transactional RCS request to the /v1/rcs/send endpoint.

2. Insider One validates the request, resolves your RCS provider credentials (Infobip or Sinch), and queues the message for delivery with a 202 Accepted response and a messageId.

3. Insider One sends the message through your configured RCS provider (Infobip or Sinch), which then delivers it to the recipient's device.

4. If you've configured a callback URL, Insider One sends delivery and failure events to that endpoint. These events use the same webhook format as Transactional SMS, so you can reuse the same webhook handler. Read and seen events are available in analytics only and aren't sent to your callback.

5. If you enable fallback and RCS delivery fails for an eligible reason (for example, the recipient's device isn't RCS-capable), Insider One automatically sends your fallback SMS body via the Transactional SMS path.

Endpoint and Headers

POSThttps://sms.useinsider.com/v1/rcs/send

Headers

Body Parameters

RCS Content

The rcsContent object defines the RCS message sent to the recipient.

• Text message (type: "text"): provide a non-empty text field. Don't include cards.

• Media message (type: "media"): provide one or more cards (max 6). Don't include text. Each card supports:

Each CTA button has:

A single card renders as a rich card. Multiple cards render as a carousel.

Sample Request

Every request requires a JSON body. Before sending your request, ensure that you replace the sample values in the request header(s) and body where required.

Text RCS with SMS Fallback

curl --location 'https://sms.useinsider.com/v1/rcs/send' \
--header 'x-ins-auth-key: INS.Abcd1234' \
--header 'Content-Type: application/json' \
--data '{
    "to": "+905555555555",
    "rcsContent": {
        "type": "text",
        "text": "Your order #12345 has shipped and will arrive soon."
    },
    "fallbackEnabled": true,
    "fallbackContent": "Your order #12345 has shipped! Track it here: https://shop.example/o/12345",
    "fallbackSender": "VIK_SMS",
    "callback": "http://callback.url",
    "uniqueArgs": {
        "orderId": "12345"
    }
}'

Media RCS (Rich Card)

curl --location 'https://sms.useinsider.com/v1/rcs/send' \
--header 'x-ins-auth-key: INS.Abcd1234' \
--header 'Content-Type: application/json' \
--data '{
    "to": "+905555555555",
    "rcsContent": {
        "type": "media",
        "cards": [
            {
                "type": "image",
                "media": "https://example.com/order.jpg",
                "header": "Order Confirmed",
                "text": "Thanks for your purchase! Your order is on its way.",
                "buttonType": "cta",
                "buttons": [
                    {
                        "action": "custom_link",
                        "target": "https://shop.example/o/12345",
                        "text": "View Order"
                    }
                ]
            }
        ]
    },
    "callback": "http://callback.url",
    "uniqueArgs": {
        "orderId": "12345"
    }
}'

Sample Responses

On success, the API responds with a 202 Accepted status and the generated message ID. Use this messageId to correlate the webhook events you receive on your callback URL.

{
  "message": "Accepted",
  "messageId": "rcs-a1b2c3d4e5f6a7b8c9"
}

Error Codes

If a request can't be processed, the API returns an HTTP status code together with an errorCode and a descriptive message. Validation errors also include an errors array that identifies the affected fields.

SMS Fallback

Transactional RCS can automatically fall back to SMS when an RCS message can't be delivered, so time-sensitive transactional messages still reach the user.

Here's how it works:

• Set fallbackEnabled: true and provide a fallbackContent SMS body (required when fallback is enabled). Optionally set fallbackSender.

• At submission time, Insider One stores the fallback SMS so it can be sent automatically if RCS delivery fails for an eligible reason.

• If RCS delivery is reported undelivered for a fallback-eligible reason (for example, the recipient's device isn't RCS-capable), Insider One automatically sends the fallback SMS through the Transactional SMS path, so no second API call is required.

• The fallback SMS is created from fallbackContent, not from your RCS message. This allows you to customize the SMS separately, since RCS content and formatting might not be suitable for SMS.

• You'll receive the standard Transactional SMS callback events for the fallback message, in addition to the txn_rcs_undelivered RCS event.

If fallbackEnabled is false (or no eligible fallback applies), an undelivered RCS message is simply reported as txn_rcs_undelivered with no SMS sent.

Fallback if you don’t have sMS Quota

SMS quota for transactional messaging is enforced as a country-based allowlist: you have a quota only for the countries configured in your transactional SMS Settings. It's important to understand when this quota is evaluated for a fallback message:

• At RCS submission time, the /v1/rcs/send request is not blocked by SMS quota. When fallbackEnabled is true, Insider One reads your country-based SMS quota and stores it alongside the fallback SMS payload, but it doesn't reject the RCS submission if that quota is empty or doesn't cover the recipient's country. The RCS message is still accepted with 202 Accepted and sent over RCS as normal.

• When fallback is triggered (RCS reported undelivered for an eligible reason), the stored SMS payload, including the country-based quota captured at submission time, is dispatched through the Transactional SMS path. At that point, the SMS path checks the recipient's country against the allowlist.

So, if you have no SMS quota for the recipient's country at the moment fallback fires:

• The fallback SMS is dropped by the SMS dispatch path with an Invalid Country Code result (drop code 2002); it isn't delivered.

• The RCS event you already received remains txn_rcs_undelivered. The dropped fallback then produces the standard Transactional SMS callback events for that dropped message on your callback URL, so the drop is observable through the normal SMS webhook (not through a separate RCS-specific error).

• The original RCS message is unaffected; only the SMS fallback attempt is dropped.

In short: a missing SMS quota never prevents the RCS message itself from being accepted or sent. It only causes the fallback SMS to be dropped at delivery time if the recipient's country isn't in your SMS allowlist. To guarantee fallback coverage for a given destination, make sure your transactional SMS quota includes that recipient's country.

Limitations

• All requests must be made with a simple HTTPS POST.

• The API Key must be provided in the request header. An incorrect key returns an authorization error.

• Transactional RCS must be enabled for your panel. RCS is delivered via Infobip or Sinch providers only.

• The phone number must be in E.164 format.

• For text messages, rcsContent.text is required. For media messages, at least one card is required.

• A media message may contain a maximum of 6 cards, and each card may contain a maximum of 4 CTA buttons.

• When fallbackEnabled is true, fallbackContent is required and limited to 670 characters.