Send Multiple Transactional RCS Messages (Batch)

You can use the Multiple Transactional Batch RCS API to send individually triggered RCS (Rich Communication Services) messages to multiple recipients in a single request. Each request can contain up to 20 messages, eliminating the need to call the transactional single RCS endpoint separately for each recipient.

Use this API when a specific event in your system triggers transactional messages for multiple recipients at once.

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 callback URLs and receive delivery events.

Endpoint and headers

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

Headers

Body parameters

The request body contains the shared batch configuration and a messages array for recipient-specific message details.

All messages in a batch share the same SMS fallback configuration. The fallbackEnabled and fallbackSender fields are configured once at the batch level and apply to every message in the request.

Message object parameters

Each object in the messages array contains the following fields.

fallbackEnabled and fallbackSender are configured once at the batch level and apply to every message in the request. You cannot enable SMS fallback for only selected recipients within the same batch. However, fallbackContent must be provided separately for each recipient when SMS fallback is enabled.

Each recipient can have different rcsContent, fallbackContent, callback, uniqueArgs, and settings values, including URL shortening and click tracking settings.

Sample Request

Every request requires a JSON body containing the messages array. Before sending your request, replace the sample values in the request headers and body where required.

curl --location 'https://sms.useinsider.com/v1/rcs/sendMultipleMessage' \
--header 'x-ins-auth-key: INS.Abcd1234' \
--header 'Content-Type: application/json' \
--data '{
    "fallbackEnabled": true,
    "fallbackSender": "VIK_SMS",
    "messages": [
        {
            "phoneNumber": "+905555555555",
            "rcsContent": {
                "type": "text",
                "text": "Your order #12345 has shipped."
            },
            "fallbackContent": "Your order #12345 has shipped! https://shop.example/o/12345",
            "callback": "http://callback.url",
            "uniqueArgs": {
                "orderId": "12345"
            }
        },
        {
            "phoneNumber": "+905555555556",
            "rcsContent": {
                "type": "media",
                "cards": [
                    {
                        "type": "image",
                        "media": "https://example.com/order.jpg",
                        "header": "Order Confirmed",
                        "text": "Your order is on its way.",
                        "buttonType": "cta",
                        "buttons": [
                            {
                                "action": "custom_link",
                                "target": "https://shop.example/o/12346",
                                "text": "View Order"
                            }
                        ]
                    }
                ]
            },
            "fallbackContent": "Your order #12346 is on its way.",
            "callback": "http://callback.url",
            "uniqueArgs": {
                "orderId": "12346"
            }
        }
    ]
}'

Sample Responses

The API supports partial success. The response includes the accepted messages together with their generated message IDs and phone numbers. Messages that fail validation are returned separately in the errors array.

{
  "message": "Accepted",
  "messageIds": [
    {
      "phoneNumber": "+905555555555",
      "messageSid": "rcs-a1b2c3d4e5f6a7b8c9"
    }
  ],
  "errors": []
}

Error Codes

If a request cannot 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 cannot be delivered, helping time-sensitive transactional messages reach the recipient.

SMS fallback works as follows:

• Set fallbackEnabled: true at the batch level and provide a fallbackContent SMS body for each recipient. You can optionally provide fallbackSender.

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

• If an RCS message is reported as undelivered for a fallback-eligible reason, such as the recipient's device not supporting RCS, Insider One automatically sends the corresponding fallback SMS through the Transactional SMS path. No additional API request is required.

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

• You 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 the delivery failure is not eligible for fallback, the undelivered RCS message is reported as txn_rcs_undelivered and no SMS is sent.

Fallback if you do not have SMS quota

Transactional SMS quota is managed through a country-based allowlist. You have quota only for the countries configured in your transactional SMS settings. The quota is evaluated differently when the RCS request is submitted and when SMS fallback is triggered.

• At RCS submission time: The batch request is not blocked by SMS quota. When fallbackEnabled is true, Insider One reads your country-based SMS quota and stores it together with each fallback SMS. The RCS request is not rejected if the quota is empty or does not include the recipient's country. The RCS message is still accepted with a 202 Accepted response and sent through RCS.

• When fallback is triggered: If RCS delivery fails for an eligible reason, Insider One sends the stored SMS payload through the Transactional SMS path. The SMS path then checks whether the recipient's country is included in the country-based allowlist captured at submission time.

If you do not have SMS quota for the recipient's country when fallback is triggered:

• The fallback SMS is dropped with an Invalid Country Code result and drop code 2002. The SMS is not delivered.

• The original RCS event remains txn_rcs_undelivered. The dropped SMS fallback generates the standard Transactional SMS callback events on the callback URL configured for that recipient. The drop is therefore reported through the standard SMS webhook rather than through a separate RCS-specific error.

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

A missing SMS quota does not prevent the RCS message from being accepted or sent. It only causes the fallback SMS to be dropped if the recipient's country is not included in your SMS allowlist. To provide SMS fallback for a destination, make sure your transactional SMS quota includes the recipient's country.

Limitations

• All requests must be sent using an HTTPS POST request.

• The API key must be included in the request header. An invalid API key returns an authorization error.

• Transactional RCS must be enabled for your panel. RCS messages can be delivered through Infobip or Sinch only.

• Each batch request can contain up to 20 messages.

• Recipient phone numbers must use the E.164 format.

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

• Quick-reply buttons are unavailable for Transactional RCS. Only none and cta button types are supported.

• A media message can contain up to 6 cards. Each card can contain up to 4 CTA buttons.

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