Send RCS Template Message ^New

Pre-requisites

To send an RCS message, you will need to

Register your Brand with Exotel
Have the RCS templates configured for your brand
Get your Brand and bot verified to send messages to a larger audience

Please use this link to register with us and understand more about RCS. If you are an existing customer who wants to use RCS, please get in touch with your Account Manager/Support team and we will surely assist you

This API can send messages to a single number with a message content or different numbers with different message contents for each number. To send a message through Exotel API, you will need to make an HTTP POST request to:

POST

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/messages

Replace <your_api_key> and <your_api_token> with the API key and token created by you.
Replace <your_sid> with your “Account sid".
Replace <subdomain> with the region of your account
1. <subdomain> of Singapore cluster is @api.exotel.com
2. <subdomain> of Mumbai cluster is @api.in.exotel.com

<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

The following are the POST parameters -

Parameter Name	Parameter Type	Mandatory/Optional	Value
custom_data	String	Optional	This parameter can be used to send any custom data at the API request level. This will be passed back in the callback.
status_callback	String (URL)	Optional	Once the message reaches terminal state, Exotel will do a POST callback to your end point if the URL is set as a parameter in the API.
rcs	Channel Object	Optional	Information related to the messages to be sent out on RCS.

* The RCS parameter mentioned here will be used to send messages through RCS communication channel. In future the API will be extended further to support other communication channels like SMS. Later, SMS parameter can also be passed to send SMSes.

Channel Object

Parameter Name	Parameter Type	Mandatory/Optional	Value
custom_data	String	Optional	This parameter can be used to send any custom data at the API request level. This will be passed back in the callback.
status_callback	String (URL)	Optional	Once the message reaches terminal state, Exotel will do a POST callback to your end point if the URL is set as a parameter in the API.
messages	[]Message Object	Mandatory	Array of messages to be sent out

Message Object

Parameter Name	Parameter Type	Mandatory/Optional	Value
custom_data	String	Optional	This parameter can be used to send any custom data at the API request level. This will be passed back in the callback.
status_callback	String (URL)	Optional	Once the message reaches terminal state, Exotel will do a POST callback to your end point if the URL is set as a parameter in the API.
from	String	Mandatory	BotID from which the message has to be sent.
to	String	Mandatory	Phone number of the user to whom a message needs to be sent. The number must be in e.164 format. Here are some examples of supported phone number formats: "+10000000000" "+919888888888" "+919876543210"
content	RCS Message Object	Mandatory	RCS message body
fallback	FallbackObject	Optional	Fallback SMS object

TemplateMessageObject

Parameter Name	Parameter Type	Mandatory/Optional	Value
name	String	Mandatory	Name of the template
variables	VariablesObject	Mandatory	Variables for the template in the follwing format:

VariablesObject

Parameter Name	Parameter Type	Mandatory/Optional	Value
TemplateParam1	String	Optional	TemplateParam1_Value
TemplateParam2	String	Optional	TemplateParam2_Value
TemplateParam3	String	Optional	TemplateParam3_Value
.
.

FallbackObject

Parameter Name	Parameter Type	Mandatory/Optional	Value
from	String	Mandatory	SMS sender Id from which the message has to be sent.
content	SmsBodyObject	Mandatory	sms message body

SmsBodyObject

Note : These parameters are same as single send SMS parameters in : Product-SMS

Parameter Name	Parameter Type	Mandatory/Optional	Value
dlt_entity_id	String	Optional (Globally) Mandatory (India)	Applicable only for SMS sent by Indian businesses to Indian destination numbers. Your Entity Id as registered on DLT (Distributed Ledger Technology) portal of operators in India. This is mandatory to be passed in API or configured on Dashboard for SMS towards Indian destination (Learn More about DLT)
dlt_template_id	String	Optional	Applicable only for SMS sent by Indian businesses to Indian destination numbers. Content Template Id against the SMS body registered with DLT (Distributed Ledger Technology) portal of operators in India. (Learn More about DLT)
text	String	Mandatory	Message Body
sms_type	String	Mandatory	transactional (OTP or Service Implicit content) transactional_opt_in (Service Explicit content) promotional (Promotional content with numeric header)
encoding_type	String	Optional	Message type of SMS; plain or unicode
priority	String	Optional	Priority of the SMS; normal or high. Priority=high parameter should only be used for OTP SMSes (Bank or Delivery). Using it for any other SMS may impact your delivery
shorten_url	boolean	Optional	Whether to shorten the URLs present in the SMS. Can be: "true" or "false". Please note that it is a chargeable feature and you can refer to Support article to understand more and get it enabled for your account.
shorten_url_params	ShortenUrlParamsObject	Optional	Parameters for different features related to Shortend URL

ShortenUrlParamsObject

Parameter Name	Parameter Type	Mandatory/Optional	Value
custom_domain	String	Optional	Whether you want the short URL to start with default domain- exo.tl or you want to provide a custom domain of your own choice. If custom domain is not present or empty, we will use the default domain(exo.tl) If custom domain is given in the request it will be used to form the short URLNote : Clients will have to route the traffic on their custom domain to exo.tl domain, this is a change on your domain management system
tracking	boolean	Optional	Whether to track the URLs present in the SMS. Can be: "true" or "false". "ShortenUrl" needs to be "true" for Tracking to work. This feature is currently available to select customers. For early access, please fill this form.
click_tracking_callback_url	String(URL)	Optional	Once someone clicks on the shortened URL, Exotel will do a POST callback to your end point if the URL is set as a parameter in the API.

Sample request of sending a RCS template message
cURL - RCS Template
cURL - RCS template with SMS fallback

curl -XPOST "https://<api_key>:<api_token><subdomain>/v2/accounts/<your_sid>/messages"
-d 
'{
    "custom_data": "ORDER123456",
    "status_callback": "https://pipedream.net",
    "rcs": {
        "messages": [
            {
                "from": "IifqFxxxxxxx6fp",
                "to": "+91xxxxxxx987",
                "content": {
                    "type": "template",
                    "template": {
                        "name": "Exotel_test"
                    }
                }
            }
        ]
    }
}'

curl -XPOST "https://<api_key>:<api_token><subdomain>/v2/accounts/<your_sid>/messages"
-d 
'{
    "custom_data": "ORDER123456",
    "status_callback": "https://eoh4ziqcxm13rgr.m.pipedream.net",
    "rcs": {
        "messages": [
            {
                "from": "IifqFxxxxxxx6fp",
                "to": "+91xxxxxxx987",
                "content": {
                    "type": "template",
                    "template": {
                        "name": "ShippedMessage",
                        "variables": {
                            "name":"Exotel",
                            "ORDER_ID": "123456"
                        }
                    }
                },
                "fallback": {
                    "sms": {
                        "messages": {
                            "from": "EXOTEL",
                            "content": {
                                "dlt_entity_id": "110xxxxxxxxxx127",
                                "dlt_template_id": "120xxxxxxxxxxx065",
                                "sms_type": "transactional",
                                "text":"Hi there. This is a test message from Exotel",
                                "priority": "high"
                            }
                        }
                    }
                }
            }
        ]
    }
}'

HTTPS Response

On success, the HTTP response status code will be 202
The Sid is the unique identifier of the message and it will be useful to log this for future debugging
the HTTP body will contain an JSON similar to the one below

Example Response
JSON

{
   "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"
           }
         }
       ]
     }
   }
}

Following are the response parameters

Parameter	Type	Mandatory/Optional	Notes
request_id	String	Mandatory	This indicates the unique id of the request. Useful for debugging and tracing purposes.
method	String	Mandatory	This indicates the HTTP method for the request such as POST
http_code	Integer	Mandatory	This indicates the HTTP code for the request such as 202, 400, 500 etc.
metadata	MetadataObject	Mandatory	Metadata pertaining to the request. Count of failed, total and success records.
response	ResponseObject	Mandatory	Response for the request

MetadataObject

Parameter	Type	Mandatory/Optional	Notes
total	Integer	Mandatory	Total number of the messages in the request
success	Integer	Mandatory	Number of messages successfully accepted
failed	Integer	Mandatory	Number of messages that couldn’t be accepted (failed)

ResponseObject

Parameter	Type	Mandatory/Optional	Notes
rcs	ChannelResponseObject	Mandatory	Response for RCS messages specified in the request

ChannelResponseObject

Parameter	Type	Mandatory/Optional	Notes
messages	[]CreateMessageResponseObject	Mandatory	Array of messages response for each message

CreateMessageResponseObject

Parameter	Type	Mandatory/Optional	Notes
code	Integer	Mandatory	Response code for the individual message
error_data	ErrorResponseObject	Optional	Error related to a single message
status	String	Mandatory	Status of the single message
data	MessageResponseObject	Optional	Data pertaining to a single message

ErrorResponseObject

Parameter	Type	Mandatory/Optional	Notes
code	Numeric	Mandatory	Numeric HTTP code for a Single message
message	String	Mandatory	Brief description of the error
description	String	Mandatory	Detailed explanation of error

MessageResponseObject

Parameter	Type	Mandatory/Optional	Notes
sid	String	Mandatory	SID (Unique identifier) of the single message

HTTP Error Codes

HTTP Error Codes	Error Message
202	Accepted - Request accepted.
400	Bad Request - Something in your header or request body was malformed/missing. More than 100 messages specified in a request
401	Unauthorized - Necessary credentials were either missing or invalid.
402	Payment Required - The action is not available on your plan, or you have exceeded usage limits for your current plan.
403	Your credentials are valid, but you don’t have access to the requested resource.
404	Not Found - The object you’re requesting doesn’t exist.
5xx	Server Errors - Something went wrong at our end. Please try again.

RCS Status Callback ^New

Status callback URL can be passed in status_callback parameter in send message/template message APIs and it can also be configured as default to receive the responses.

If you pass status callback URL in send message/template message APIs, status callbacks will be triggered to the respective URL
If you do not pass any status callback URL in send message/template message APIs, status callbacks will be triggered to the default URL, if any.

Fallback Status Callbacks :

If SMS Fallback contract was passed while sending rcs message, in case of failure of sending an RCS message, sms fallback will be triggered with the provided details .

if sms triggering is unsuccessful, the failure callback will be sent with null message_sid and sms_units, along with the relevant error exo status details.

*NOTE: Any callback can be received only in one status callback URL at any time

Callback Parameter

Parameter	Type	Mandatory	Notes
rcs	MessageDLRObject	Optional	Delivery report (DLR) of the RCS channel
sms	SMSDLRObject	Optional	Delivery report (DLR) of the SMS Fallback

MessageDLRObject

Parameter	Type	Mandatory	Notes
messages	[]RCSMessageDLRObject	Mandatory	Information relating to the messages for DLR

RCSMessageDLRObject

Parameter	Type	Mandatory	Notes
callback_type	String	Mandatory	Type of the callback. Possible values: dlr, icm
sid	String	Mandatory	SID (Unique Identifier) of the message
to	String	Mandatory	Phone Number of the user to whom the message was sent.
exo_status_code	Integer	Mandatory	ExoStatusCode for the message
exo_detailed_status	String	Mandatory	Detailed status of ExoStatus code
description	String	Mandatory	Description of the ExoStatus code
timestamp	String	Mandatory	Timestamp at which the event occurred
custom_data	String	Optional	It will return the custom data, if the same was passed in the API request

SMSDLRObject

Parameter	Type	Mandatory	Notes
messages	[]SmsMessageDLRObject	Mandatory	Information relating to the messages for DLR

SmsMessageDLRObject

Parameter	Type	Mandatory	Notes
callback_type	String	Mandatory	Type of the callback. Possible values: dlr
sid	String	Mandatory	SID (Unique Identifier) of the message.
channel_sid	String	Mandatory	Sid of the fallback channel of exotel Platform. Will be `null` for failure to trigger the fallback channel.
to	String	Mandatory	Phone Number of the user to whom the message was sent.
exo_status_code	Integer	Mandatory	ExoStatusCode for the message
exo_detailed_status	String	Mandatory	Detailed status of ExoStatus code
description	String	Mandatory	Description of the ExoStatus code
sms_units	Integer	Mandatory	The number of SMS units being sent. Will be `null` for failure to trigger SMS
timestamp	String	Mandatory	Timestamp at which the event occurred
custom_data	String	Optional	It will return the custom data, if the same was passed in the API request

ExoStatus Codes

Detailed Status Code	Detailed Status	Description
40001	EX_MESSAGE_SENT	The message has been sent to the user
40002	EX_MESSAGE_DELIVERED	The message has been successfully delivered to the user
40003	EX_MESSAGE_SEEN	The message has been seen by the user
40004	EX_SYSTEM_ERROR	The message failed due to an issue with the system. For eg: Authentication/Access Token/Permission related issue, service not available issue etc.

Fallback SMS ExoStatus Codes :

Kindly refer to the Status Code section in our SMS API documentation

{
    "rcs": {
        "messages": [
            {
                "callback_type": "dlr",
                "sid": "1234",
                "to": "236556496",
                "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"
            }
        ]
    }
}

{
    "rcs": {
        "messages": [
            {
                "callback_type": "dlr",
                "sid": "1234",
                "to": "236556496",
                "exo_status_code": 40003,
                "exo_detailed_status": "EX_MESSAGE_SEEN",
                "description": "Message delivered",
                "timestamp": "2022-14-07T17:00:00.000+05:30",
                "custom_data": "ORDER123456"
            }
        ]
    }
}

{
  "sms": {
    "messages": [
      {
        "callback_type": "dlr",
        "sid": "112f34e42fc338d14d52af17de13175p",
        "message_sid": "f95b66263806e5b577bc002aa458175p",
        "to": "236556496",
        "exo_status_code": 20005,
        "exo_detailed_status": "DELIVERED_TO_HANDSET",
        "description": "DELIVERED_TO_HANDSET",
        "sms_units": 1,
        "timestamp": "2024-12-18 23:18:30"
      }
    ]
  }
}

{
  "sms": {
    "messages": [
      {
        "callback_type": "dlr",
        "sid": "0efaecd0e1611b325456ea4e1d54175a",
        "message_sid": null,
        "to": "236556496",
        "exo_status_code": 23286,
        "exo_detailed_status": "EX_EMTPY_BODY",
        "description": "message body cannot be empty.",
        "sms_units": null,
        "timestamp": "2024-12-18T13:54:52+05:30",
        "custom_data": "ORDER123456"
      }
    ]
  }
}

Receive RCS Incoming Message ^New

Receive Messages Webhook

Receive messages webhook can be passed in status_callback parameter in send message/template message APIs to receive replies on messages from the business. To receive any message from an end user which is not a reply to a business message, a default callback value needs to be configured. Exotel team will help you configure the default URL while onboarding.

If you pass receive messages webhook in send message/template message APIs, reply messages from users will be triggered to the respective URL
If you do not pass any receive messages webhook in send message/template message APIs, reply messages from users will be triggered to the default URL, if any.
All user initiated conversations and messages which are not a reply on business message, will be triggered to the default URL

*NOTE: Any messages from an user can be received only in one webhook at any time

Webhook Parameter

Parameter	Type	Mandatory	Notes
rcs	MessageICMObject	Mandatory	Incoming message callback for RCS

MessageICMObject

Parameter	Type	Mandatory	Notes
messages	[]RCSMessageICMObject	Mandatory	Information relating to the incoming messages from the end-users

RCSMessageICMObject

Parameter	Type	Mandatory	Notes
callback_type	String	Mandatory	Type of the callback. Possible values: dlr/icm
sid	String	Mandatory	Unique identifier of the incoming message
from	String	Mandatory	Number of the end user who has sent the incoming message to the business
to	String	Mandatory	Business number to whom the message was sent
timestamp	String	Mandatory	Timestamp at which incoming message was sent
content	ContentObject	Mandatory	Content related to the incoming message

ContentObject

Parameter	Type	Mandatory	Notes
type	String	Mandatory	Type of the message
text	String	Optional	Mandatory if type is text
file	FileIncomingMessageObject	Optional	Mandatory if type is file
location	LocationIncomingMessageObject	Optional	Mandatory if type is location
Suggested	SuggestedIncomingMessageObject	Optional	Mandatory if type is suggested
error	MessageICMErrorObject	Optional	If there is an error

FileIncomingMessageObject

Parameter	Type	Mandatory	Notes
url	String	Mandatory	URL to download the media
name	String	Optional	This is passed if the media is document. Describes the filename for the specific document.
type	String	Mandatory	Type of the file
size	Integer	Mandatory	Size of the file
thumbnail_url	String	Optional	URL of the thumbnail
thumbnail_type	String	Optional	Type of the thumbnail
thumbnail_size	Integer	Optional	Size of the thumbnail

LocationIncomingMessageObject

Parameter	Type	Mandatory	Notes
latitude	Float	Mandatory	Latitude of the location
longitude	Float	Mandatory	Longitude of the location

SuggestedIncomingMessageObject

Parameter	Type	Mandatory	Notes
Response	SuggestedResponseIncomingMessageObject	Mandatory	Response for suggested for reply/action

SuggestedResponseIncomingMessageObject

Parameter	Type	Mandatory	Notes
Reply	ReplyObject	Mandatory	Suggested Reply
Action	ActionObject	Mandatory	Suggested Action

{
    "rcs": {
        "messages": [
            {
                "callback_type": "incoming_message",
                "sid": "1234",
                "from": "5678",
                "to": "9012",
                "timestamp": "2024-12-07T17:00:00.000+05:30",
                "content": {
                    "type": "text",
                    "text": "This is a text message from RCS"
                }
            }
        ]
    }
}

{
    "rcs": {
        "messages": [
            {
                "callback_type": "incoming_message",
                "sid": "1234",
                "from": "5678",
                "to": "9012",
                "timestamp": "2024-12-07T17:00:00.000+05:30",
                "content": {
                    "type": "file",
                    "file": {
                        "url": "https://rcs-user-content-ap.storage.googleapis.com/040ee868-9e0c-4a3a-b24b-c559987dfeb7/725738ceec470d8574c0050c497d8bfc6a76e78e405e8b99438b3b23d764",
                        "name": "xyz.jpg",
                        "type": "image/jpeg",
                        "size": 187662,
                        "thumbnail_url": "https://rcs-user-content-ap.storage.googleapis.com/040ee868-9e0c-4a3a-b24b-c559987dfeb7/df6dccf930b934682505128f9c54e14dade8603bc5384a6a8e846496c8bc",
                        "thumbnail_type": "image/jpeg",
                        "thumbnail_size": 7534
                    }
                }
            }
        ]
    }
}

{
    "rcs": {
        "messages": [
            {
                "callback_type": "incoming_message",
                "sid": "1234",
                "from": "5678",
                "to": "9012",
                "timestamp": "2024-12-07T17:00:00.000+05:30",
                "content": {
                    "type": "location",
                    "location": {
                        "longtitude": 74.3043942,
                        "latitude": 29.6305248
                    }
                }
            }
        ]
    }
}

{
  "rcs": {
    "messages": [
      {
        "callback_type": "incoming_message",
        "sid": "1234",
        "from": "5678",
        "to": "9012",
        "timestamp": "2024-12-07T17:00:00.000+05:30",
        "content": {
          "type": "suggested",
          "suggested": {
            "response": {
              "action": {
                "postback": {
                  "data": "set_by_chatbot_open_url"
                },
                "text": "Show now"
              }
            }
          }
        }
      }
    ]
  }
}

{
  "rcs": {
    "messages": [
      {
        "callback_type": "incoming_message",
        "sid": "1234",
        "from": "5678",
        "to": "9012",
        "timestamp": "2024-12-07T17:00:00.000+05:30",
        "content": {
          "type": "suggested",
          "suggested": {
            "response": {
              "reply": {
                "text": "Know more",
                "postback": {
                  "data": "user_query"
                }
              }
            }
          }
        }
      }
    ]
  }
}

{
    "rcs": {
        "messages": [
            {
                "callback_type": "incoming_message",
                "from": "1234",
                "profile_name": "John",
                "to": "5698",
                "timestamp": "1235654654",
                "content": {
                    "error": {
                        "exo_status_code": 24501,
                        "exo_detailed_status": "EX_UNSUPPORTED_MEDIA_TYPE",
                        "description": "The media type is currently not supported"
                    }
                }
            }
        ]
    }
}

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

Lead Assist

Users

ExoVerify

Whatsapp

URL shortening

More...