×

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.  

 

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
{
   "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.