Exotel Developer Portal

To get the details of a SMS (including Status, Direction, etc.), you will need to make a HTTP GET request to

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/SMS/Messages/<SmsSid>

where <SmsSid> is the Sid of the SMS.

If you’d prefer response in JSON format, just append .json at the end of the HTTP POST request.

SmsSid is an alpha-numeric unique identifier generated for all the SMS sent via Exotel

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

curl https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/SMS/Messages/0b6c6a98f32682862ce6edf1bdab3526

var request = require('request');

var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/SMS/Messages/0b6c6a98f32682862ce6edf1bdab3526'
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array();
$response = Requests::get('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/SMS/Messages/0b6c6a98f32682862ce6edf1bdab3526', $headers);

import requests

requests.get('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/SMS/Messages/0b6c6a98f32682862ce6edf1bdab3526')

require 'net/http'
require 'uri'

uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/SMS/Messages/0b6c6a98f32682862ce6edf1bdab3526")
response = Net::HTTP.get_response(uri)

# response.code
# response.body

HTTP Response:

On success, the HTTP response status code will be 200
the HTTP body will contain an XML similar to the one below

Example Response
JSON
XML

{
  "SMSMessage": {
    "Sid": "0f477d60517e6e6a0f6d9a7e9af8630e",
    "AccountSid": "Exotel",
    "From": "0XXXXXX4890/WEBDEV",
    "To": "0XXXXX30240",
    "DateCreated": "2017-03-03 14:14:20",
    "DateUpdated": "2017-03-03 14:14:20",
    "DateSent": "1970-01-01 05:30:00",
    "Body": "Hello World!",
    "Direction": "outbound-api",
    "Uri": "/v1/Accounts/Exotel/SMS/Messages/0f477d60517e6e6a0f6d9a7e9af8630e.json",
    "ApiVersion": null,
    "Price": null,
    "Status": "submitted",
    "DetailedStatusCode": "21020",
    "DetailedStatus": "PENDING_ON_OPERATOR",    
    "SmsUnits": 1
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
 <SMSMessage>
  <Sid>0f477d60517e6e6a0f6d9a7e9af8630e</Sid>
  <AccountSid>Exotel</AccountSid>
  <From>0XXXXXX4890/WEBDEV</From>
  <To>XXXXX30240</To>
  <DateCreated>2017-03-03 14:14:20</DateCreated>
  <DateUpdated>2017-03-03 14:14:20</DateUpdated>
  <DateSent>1970-01-01 05:30:00</DateSent>
  <Body>Hello World!</Body>
  <Direction>outbound-api</Direction>
  <Uri>/v1/Accounts/Exotel/SMS/Messages/0f477d60517e6e6a0f6d9a7e9af8630e</Uri>
  <ApiVersion/>
  <Price/>
  <Status>submitted</Status>
  <DetailedStatusCode>21020</DetailedStatusCode>
  <DetailedStatus>PENDING_ON_OPERATOR</DetailedStatus>
  <SmsUnits>1</SmsUnits>
 </SMSMessage>
</TwilioResponse>

Description of parameters mentioned in the above response:

Parameter Name	Type & Value
Sid	string; an alpha-numeric unique identifier of the SMS
AccountSid	String; Your account identifier
From	String; It is of format <VN>/<SenderID> where <VN> is your Exotel Virtual Number/ExoPhone through which you are sending the SMS. <SenderID> is the SenderID via which this SMS was sent
To	String; Mobile number to which SMS was sent. Preferably in E.164 format. If not set, our system will try to match it with a country and route the SMS
DateCreated	Time in format YYYY-MM-DD HH:mm:ss; The time when the SMS was received at our server
DateUpdated	Time in format YYYY-MM-DD HH:mm:ss; The time when any property of this SMS was last updated by our server
DateSent	Time in format YYYY-MM-DD HH:mm:ss; The time when the SMS was delivered to the recepient
Body	String; The body of the SMS message sent
Status	Can be of: queued - This means that the SMS you have sent has been queued internally for delivery sending - This means that we're in process of sending the SMS to upstream provider/gateway submitted - This means that the SMS you have sent has been submitted from our system to SMS Gateway sent - The SMS was successfully delivered to the handset failed-dnd - The delivery of the SMS failed because the number belongs to the TRAI NCPR list. This is applicable only for promotional SMS failed - The delivery of SMS failed. Please see DetailedStatusCode and DetailedStatus for further details.
DetailedStatus	Human readable word that explains what happened to the Message. Log these strings in your log files for grepping and debugging by a developer.
DetailedStatusCode	Exotel’s Detailed Status code corresponding to the DetailedStatus. Use this field to build decision making in your code.
Price	Double; If present, this will be the amount (in INR) you have been charged for the SMS
Direction	incoming - incoming messages outbound-api - messages initiated via the REST API outbound-call - messages initiated during a call outbound-reply - messages initiated in response to an incoming message
Uri	Uri is the path of the SmsSid
SmsUnits	The number of SMS units being sent

Mapping and Description of status codes

Detailed Status Code	Nature of Detailed Status Code	Status	DetailedStatus	What it means
21010	Intermediate, may change in future	queued	PENDING_TO_OPERATOR	The message is is being processed by Exotel.
21015	Intermediate, may change in future	sending	SENDING_TO_OPERATOR	The message has been processed by Exotel and is en-route to the operator.
21020	Intermediate, may change in future	submitted	PENDING_ON_OPERATOR	The message has been successfully Submitted to the operator and is pending delivery. In India, Promotional SMS may be in this state if submitted outside permitted time (10AM to 9PM).
20005	Final	sent	DELIVERED_TO_HANDSET	We know with confidence that the message has been delivered to recipient's handset.
20006	Final	sent	DELIVERED_TO_OPERATOR	The message has been delivered to operator. In some regions and routes, handset delivery status (DELIVERED_TO_HANDSET) is not available and hence this is the best we can ever report about the delivery status.
23005	Final	failed-dnd	FAILED_REJECTED_DND	The message has been rejected as the end user is a subscriber of DND (Do Not Disturb) services.
23010	Final	failed	FAILED_INVALID_DESTINATION_NUMBER	The destination number is incorrect, not SMS-enabled or is a PSTN landline.
23015	Final	failed	FAILED_SPAM_DETECTED	One of the most common reasons for SMS delivery failure is carrier level spam filters. Carriers have added systems and algorithms that detect spam content and then block these messages. Unfortunately, these filters are hidden, subject to carrier preferences, vary from carrier to carrier, and can be changed without notice.
23020	Final	failed	FAILED_REJECTED_BLACKLIST	You tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP/DND opt-out message and no longer wishes to receive messages from you.
24990	Final	failed	FAILED_UNKNOWN_ERROR	Delivering your message failed for reasons that are unknown to us and to our carriers. If you notice too many of these cases, please reach out to us.
23030	Final	failed	FAILED_UNAVAILABLE_ROUTE	The carrier and fallback carriers were not able to deliver the SMS message because no route was available.
23035	Final	failed	FAILED_SUBSCRIBER_UNAVAILABLE	This message was not delivered because subscriber was temporarily unavailable. For example, the receiving handset was out of coverage or switched off. This is a temporary failure, but a message sent to the same subscriber at a later point in time may get delivered.
23040	Final	failed	FAILED_SUBSCRIBER_UNKNOWN	Subscriber is unknown to the operators or no longer active.
23050	Final	failed	FAILED_EXPIRED	The message was sent to the operator and may have been retried several times within the default network SMS expiration duration. The message request has now expired.
23060	Final	failed	FAILED_REJECTED	For a number of reasons, the message was rejected by Exotel or the operator.
24105	Final	failed	FAILED_HANDSET_ERROR	The message was not delivered to the subscriber due to handset failure
24110	Final	failed	FAILED_OPERATOR_ERROR	The message failed due to an issue at the operator end
23070	Final	failed	FAILED_INVALID_MESSAGE	The message was rejected by the operator as Invalid. While Exotel will automatically split messages longer than 160 GSM 7-bit characters, or 70 unicode 16-bit characters into multipart SMS, Messages exceeding the allowed character limit of 2000 characters may also end in this state. Any request error related to the message, say unidentified character, may also fall under this bucket. In India, if DLT related parameters are not set like Entity ID, your SMS may fail with this error code.
23072	Final	failed	FAILED_INVALID_SENDER_ID	The message failed due to invalid or unregistered Sender ID. In case of India, if your Sender ID (header) is not registered with operator DLT platform, you may receive this error.
24010	Final	failed	FAILED_SYSTEM_ERROR	SMS failed while processing within Exotel system.
24120	Final	failed	FAILED_SUBSCRIBER_ERROR	All subscriber or recipient issues that are unrelated to the handset (For ex - Receiver does not have enough mobile balance to receive the SMS) may fall under this bucket.
23080	Final	failed	SENDER_BLOCKED_BY_DLT	Applicable only for SMS sent to Indian destination numbers via domestic lines. Sender ID (Header) is blocked or failed at DLT platform by the operator due to mismatch, non-registration, template not linked with Sender (header) etc.
23081	Final	failed	ENTITY_BLOCKED_BY_DLT	Applicable only for SMS sent to Indian destination numbers via domestic lines. Entity (DLT Entity ID) is blocked or failed at DLT platform by the operator due to DLT Entity ID not passed in API or configured on Exotel Dashboard, values are mismatching etc.
23082	Final	failed	TEMPLATE_BLOCKED_BY_DLT	Applicable only for SMS sent to Indian destination numbers via domestic lines. Template (Template ID) is blocked or failed at DLT due to Template ID not set in API or configured on Exotel Dashboard, content is not exactly matching, non-registration of the template etc.
23083	Final	failed	FAILED_DLT_SCRUBBING_ERROR	Applicable only for SMS sent to Indian destination numbers via domestic lines. SMS is blocked or failed at DLT even after registration due to explicit blocking of the Sender ID due to spam, issues with consent or any other technical issues with DLT platform.
23084	Final	failed	FAILED_DLT_CONSENT_ERROR	SMS DLT consent registration is required for you to continue sending SMS to your customers. Applicable only for SMS sent to Indian destination numbers via domestic lines.

DetailedStatusCode in the range of 23084-24000 are reserved for future and can be expanded for any other detailed status scenario related to SMS.

Exotel can push the SMS status to you after the SMS reaches any terminal state ie sent, failed or failed-dnd. For this, you need to pass an additional parameter StatusCallback along with your other parameters. This parameter should be an URL hosted by you.

Exotel will make a POST request to the StatusCallback with the following parameter:

SmsSid - The Sid (unique id) of the SMS that you got in response to your request
To - Mobile number to which SMS was sent
Status - one of: queued, sending, submitted, sent, failed-dnd, failed
DetailedStatus - Human readable word that explains what happened to the message
DetailedStatusCode - Exotel’s Detailed Status code corresponding to the DetailedStatus
DateSent - The date on which the message was sent
SmsUnits - The number of SMS units being sent

Mapping and Description of HTTP API Error codes in the API response

GET (/sms) error codes:

Scenario	HTTP Error Code	API Error code	Error message
SID not found in GET call	200	-	No matching results
If your account has sent GET requests higher than the maximum limit feasible	429	40403	Too many GET requests.
GET API call to v1/Accounts/<account-sid>/Sms/<invalid-parameter> an unrecognized SMS endpoint	400	40501	Invalid parameters

POST (/send, /bulksend) and /GET (/sms) error codes:

Scenario	HTTP Error Code	API Error code	Error message
If your account is inactive	403	40002	Account inactive.
Api call to v1/Accounts/exotel42us3/Sms	400	40500	Invalid Parameters
Unsupported API version	400		Exotel API Version $version not supported. Contact Exotel for details.
Accounts missing from URL	400		/Accounts/ missing from URL
Account sid missing from URL	403	34009	Action forbidden on given resource;
Auth key or auth token missing	401		Authentication is required to view this page.
Invalid auth key or auth token	401	34010	Unauthorized;
Invalid Account sid or any resource or action is missing or invalid	403	34009	Action forbidden on given resource;
Non alpha-numeric auth key or token	400	34001	Bad or missing parameters in request.;

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

Lead Assist

Users

ExoVerify

Whatsapp

URL shortening

More...

Voice

SMS

Exophones

Heartbeat

Call Campaigns

SMS Campaigns

LeadAssist

More...

Greeting

Connect

Passthru

Transfer

SMS

Email

More