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.

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

Exotel can push the SMS status to you after the SMS reaches any terminal state ie sentfailed 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.;