Skip to main content

RCS Omnichannel API

RCS transforms business messaging with interactive experiences — images, videos, carousels, and CTAs — beyond traditional SMS and WhatsApp. When RCS is not supported on the recipient's device, an automatic SMS fallback can be configured.

Prerequisites

To send RCS messages you need to:

  1. Register your Brand with Exotel
  2. Have RCS templates configured for your brand
  3. Get your Brand and bot verified

Contact your Account Manager or fill out the RCS Early Access form to get started.

Send RCS Template Message​

POST https://<api_key>:<api_token><subdomain>/v2/accounts/<account_sid>/messages
SubdomainRegion
@api.exotel.comSingapore
@api.in.exotel.comMumbai

POST Parameters​

ParameterTypeRequiredDescription
custom_dataStringOptionalCustom metadata passed at the request level. Returned in callbacks.
status_callbackString (URL)OptionalWebhook URL for delivery status events.
rcsChannel ObjectOptionalRCS channel configuration.

Channel Object​

ParameterTypeRequiredDescription
custom_dataStringOptionalCustom metadata at the channel level.
status_callbackString (URL)OptionalWebhook URL for channel-level delivery events.
messages[]Message ObjectMandatoryArray of messages to send.

Message Object​

ParameterTypeRequiredDescription
custom_dataStringOptionalCustom metadata at the message level.
status_callbackString (URL)OptionalWebhook URL for this specific message.
fromStringMandatoryBotID to send from (provided by Exotel during onboarding).
toStringMandatoryRecipient phone number in E.164 format (e.g., +919888888888).
contentTemplate Message ObjectMandatoryRCS message body.
fallbackFallback ObjectOptionalSMS fallback sent if RCS delivery fails.

Template Message Object​

ParameterTypeRequiredDescription
typeStringMandatoryMust be "template".
templateObjectMandatoryTemplate details.
template.nameStringMandatoryName of the pre-approved RCS template.
template.variablesVariables ObjectMandatoryKey-value pairs for template variable substitution.

Variables Object​

ParameterTypeRequiredDescription
TemplateParam1StringOptionalValue for the first template variable.
TemplateParam2StringOptionalValue for the second template variable.
TemplateParam3StringOptionalValue for additional template variables.

Fallback Object​

ParameterTypeRequiredDescription
fromStringMandatorySMS Sender ID to use for the fallback message.
contentSMS Body ObjectMandatorySMS message body.

SMS Body Object​

ParameterTypeRequiredDescription
textStringMandatorySMS message body text.
sms_typeStringMandatorytransactional, transactional_opt_in, or promotional.
dlt_entity_idStringOptional (Mandatory for India)Entity ID registered on the DLT portal (required for Indian business → Indian number SMS).
dlt_template_idStringOptionalDLT Content Template ID for the SMS body.
encoding_typeStringOptionalplain or unicode.
priorityStringOptionalnormal or high. Use high for OTP SMS only.
shorten_urlBooleanOptionalWhether to shorten URLs in the SMS. Chargeable feature.
shorten_url_paramsShorten URL Params ObjectOptionalConfiguration for URL shortening.

Shorten URL Params Object​

ParameterTypeRequiredDescription
custom_domainStringOptionalCustom domain for short URLs (defaults to exo.tl if omitted).
trackingBooleanOptionalTrack URL clicks. Requires shorten_url: true.
click_tracking_callback_urlString (URL)OptionalWebhook for click events on shortened URLs.

Code Examples​

curl -XPOST "https://<api_key>:<api_token><subdomain>/v2/accounts/<your_sid>/messages" \
-H "Content-Type: application/json" \
-d '{
    "custom_data": "ORDER123456",
    "status_callback": "https://your-server.com/callback",
    "rcs": {
        "messages": [
            {
                "from": "IifqFxxxxxxx6fp",
                "to": "+91xxxxxxxxx987",
                "content": {
                    "type": "template",
                    "template": {
                        "name": "order_confirmation",
                        "variables": {
                            "TemplateParam1": "Rahul",
                            "TemplateParam2": "ORD-12345"
                        }
                    }
                }
            }
        ]
    }
}'

Response​

HTTP 202 Accepted

{
  "request_id": "b434e927a5844175b23059cd96feea3d",
  "method": "POST",
  "http_code": 202,
  "metadata": {
    "failed": 0,
    "total": 1,
    "success": 1
  },
  "response": {
    "rcs": {
      "messages": [
        {
          "code": 202,
          "error_data": null,
          "status": "success",
          "data": {
            "sid": "2FdiiEQUosckPhpZfuVwfjxiSlc16a4"
          }
        }
      ]
    }
  }
}

Response Parameters​

ParameterTypeDescription
request_idStringUnique ID of the request. Useful for debugging.
methodStringHTTP method (e.g., POST).
http_codeIntegerHTTP status code (e.g., 202).
metadataMetadata ObjectCount of total, successful, and failed messages.
responseResponse ObjectPer-message response details.

Metadata Object: total (Integer), success (Integer), failed (Integer)

Response Object: rcs → ChannelResponseObject → messages → []CreateMessageResponseObject

CreateMessageResponseObject:

ParameterTypeDescription
codeIntegerHTTP response code for this message.
error_dataError Response ObjectError details (if failed).
statusStringsuccess or failure.
data.sidStringUnique message identifier.

Error Response Object: code (Numeric), message (String), description (String)

HTTP Error Codes​

CodeDescription
202Accepted — request accepted.
400Bad Request — malformed header/body, or more than 100 messages in one request.
401Unauthorized — credentials missing or invalid.
402Payment Required — feature not on your plan or usage limit exceeded.
403Access denied — valid credentials but no access to this resource.
404Not Found — the object does not exist.
5xxServer Error — retry the request.

RCS Status Callback​

Exotel sends delivery events to the status_callback URL provided in the API request (or the default URL configured during onboarding).

  • If status_callback is set in the API request → callbacks go to that URL.
  • If not set → callbacks go to the default URL (if configured).
  • If SMS fallback was triggered → both rcs and sms objects appear in the callback.
note

Any callback can be received only at one status callback URL at a time.

Callback Parameters​

ParameterTypeDescription
rcsMessage DLR ObjectDelivery report for the RCS channel.
smsSMS DLR ObjectDelivery report for the SMS fallback (present only if fallback was triggered).

Message DLR Object​

ParameterTypeDescription
messages[]RCS Message DLR ObjectDelivery reports for each message.

RCS Message DLR Object​

ParameterTypeDescription
callback_typeStringdlr or icm
sidStringUnique message identifier.
toStringRecipient phone number.
exo_status_codeIntegerExoStatus code (see table below).
exo_detailed_statusStringDetailed status name.
descriptionStringHuman-readable description of the status.
timestampStringISO 8601 timestamp of the event.
custom_dataStringCustom data passed in the original API request.

SMS DLR Object​

ParameterTypeDescription
messages[]SMS Message DLR ObjectDelivery reports for the SMS fallback.

SMS Message DLR Object​

ParameterTypeDescription
callback_typeStringdlr
sidStringUnique identifier of the SMS fallback message.
channel_sidStringSID of the fallback channel. null if fallback triggering failed.
toStringRecipient phone number.
exo_status_codeIntegerExoStatus code for the SMS.
exo_detailed_statusStringDetailed status name.
descriptionStringHuman-readable description.
sms_unitsIntegerNumber of SMS units sent. null if fallback triggering failed.
timestampStringISO 8601 timestamp of the event.
custom_dataStringCustom data from the original request.

RCS ExoStatus Codes​

CodeStatusDescription
40001EX_MESSAGE_SENTMessage transmitted to the user.
40002EX_MESSAGE_DELIVEREDMessage successfully delivered.
40003EX_MESSAGE_SEENMessage seen/read by the user.
40004EX_SYSTEM_ERRORDelivery failed (auth/permission/service issue).

For SMS fallback ExoStatus codes, see SMS API — Status Codes.

Callback Samples​

{
  "rcs": {
    "messages": [
      {
        "callback_type": "dlr",
        "sid": "2FdiiEQUosckPhpZfuVwfjxiSlc16a4",
        "to": "+91xxxxxxxxx987",
        "exo_status_code": 40002,
        "exo_detailed_status": "EX_MESSAGE_DELIVERED",
        "description": "Message delivered",
        "timestamp": "2024-12-07T17:00:00.000+05:30",
        "custom_data": "ORDER123456"
      }
    ]
  }
}

Receive RCS Incoming Message​

Configure a webhook to receive messages sent by users (replies or user-initiated messages). Pass the webhook URL in status_callback in the send API, or configure a default URL with the Exotel team during onboarding.

  • If status_callback is set in the send API → user replies go to that URL.
  • If not set → replies go to the default URL.
  • All user-initiated conversations (not replies to a business message) go to the default URL.
note

Any incoming message can be received only at one webhook URL at a time.

Webhook Parameter​

ParameterTypeDescription
rcsMessage ICM ObjectIncoming message callback for RCS.

Message ICM Object​

ParameterTypeDescription
messages[]RCS Message ICM ObjectArray of incoming messages.

RCS Message ICM Object​

ParameterTypeDescription
callback_typeStringincoming_message
sidStringUnique identifier of the incoming message.
fromStringPhone number of the end user.
toStringBusiness bot ID that received the message.
timestampStringISO 8601 timestamp when the message was sent.
contentContent ObjectMessage content.

Content Object​

ParameterTypeDescription
typeStringMessage type: text, file, location, suggested, or error.
textStringMessage body. Mandatory when type is text.
fileFile ICM ObjectMedia details. Mandatory when type is file.
locationLocation ICM ObjectLocation details. Mandatory when type is location.
suggestedSuggested ICM ObjectSuggested reply/action response. Mandatory when type is suggested.
errorMessage ICM Error ObjectError details. Present when type is error.

File ICM Object​

ParameterTypeDescription
urlStringURL to download the media file.
nameStringFilename (for documents).
typeStringMIME type of the file.
sizeIntegerFile size in bytes.
thumbnail_urlStringURL of the thumbnail (optional).
thumbnail_typeStringMIME type of the thumbnail (optional).
thumbnail_sizeIntegerSize of the thumbnail in bytes (optional).

Location ICM Object​

ParameterTypeDescription
latitudeFloatLatitude of the shared location.
longitudeFloatLongitude of the shared location.

Suggested ICM Object​

ParameterTypeDescription
responseSuggested Response ICM ObjectThe user's response to a suggested reply or action.

Suggested Response ICM Object: reply (Reply Object) or action (Action Object)

Incoming Message Samples​

{
  "rcs": {
    "messages": [
      {
        "callback_type": "incoming_message",
        "sid": "ICM123456",
        "from": "+91xxxxxxxxx001",
        "to": "IifqFxxxxxxx6fp",
        "timestamp": "2024-12-07T17:00:00.000+05:30",
        "content": {
          "type": "text",
          "text": "This is a text message from the user"
        }
      }
    ]
  }
}