×

Outgoing call to connect two numbers

This API will connect two numbers. It connects From Number first. Once the person at the From end picks up the phone, it will connect to the number provided as To. You can choose which number should be connected first by adding that number in the From field. An HTTP POST request is made to

POST

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect

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 sent as form-data in the Body of the Request:

Parameter Name Mandatory / Optional Value
From Mandatory String; The phone number that will be called first. Preferably in E.164 format. If not set, our system will try to match it with a country and make a call. If landline number, prefix it with STD code; Ex: 080XXXX2400
To Mandatory String; Your customer's phone number. If landline number, prefix it with STD code; Ex: 080XXXX2400
CallerId Mandatory String; This is your ExoPhone/Exotel Virtual Number (pick one from here)
CallType Optional String; trans - for Transactional Calls
TimeLimit Optional Integer; The time limit (in seconds) that you want this call to last. The call will be cut after this time (max. 14400 i.e. 4 hours)
TimeOut Optional Integer; The time (in seconds) to ring the called parties (both first and second call leg)
WaitUrl Optional

String; Play this audio to the caller. When the first leg (From) has to wait for the other leg (To) to pick up the call, the audio file specified in this parameter will be played.

Please refer this article to understand the format specifications of the audio file to be played (wav is only supported).

Guidelines on usage:

  • The audio file size is recommended to be less than 2MB. Please note, Exotel will cache the wav file. During the first few call attempts of setting this parameter, user might hear normal ringing tone for first 5 seconds (for a ~2MB file). This is only temporary for initial few calls and once the audio file is cached, audio will be played out smoothly.
  • In case you decide to change the audio file later, the WaitUrl should be different (as Exotel will cache audio file based on URL). You can do so by hosting the audio file with a different name.
  • When using this parameter, it is recommended to set the TimeOut parameter as well.

Example: "http://{your_hosted_endpoint}/{audio file name}.wav"

Record Optional

Boolean; Record the conversation of your call. The RecordingUrl will be sent to the StatusCallback URL if this is set to 'true' and the call conversation happens. Can be:

  • true - Call conversation will be recorded.
  • false (default) - Call conversation will not be recorded.

Note:- If this optional parameter is not passed then by default, calls will NOT be recorded. 

RecordingChannels Optional

String; Number of audio channels to be present in the final recording. This parameter works if Record is set to 'true'. Can be:

  • single (default) - Record both legs of the call in a single channel of the recording file.
  • dual - Record the caller and the callee into separate channels of the recording file.
RecordingFormat Optional

String; Quality of the audio recording. This parameter works if Record is set to 'true'. Can be:

  • mp3 (default) - Standard bitrate recording
  • mp3-hq - Higher bitrate (32 kbps/channel )recording.

Note:- mp3-hq option is an on-demand feature. Please reach out to hello@exotel.com or your account manager to get it enabled for your account before using this option.

CustomField Optional

Any application specific value like order id that will be passed back as a parameter in StatusCallback (only via 'terminal' StatusCallbackEvent)

StartPlaybackToNew Optional

String; The party that should listen the playback at the start of the call. Audio to be listened by agent or both customer and agent just before the call gets connected. Can be:

  • Callee (default) - Playback audio will be played to callee only.
  • Both - Playback audio will be played to both caller and callee.
StartPlaybackValueNew Optional

String; URL for the audio to be played just before the call gets connected.

Configuration for audio file supported in this playback are:

Sample Rate = 8 kHz
Bit depth = 16 bit
Bit rate = 128 kbps
Channel = mono
File Format = wav

StatusCallback Optional String; An HTTP POST request will be made to this URL depending on what events are subscribed using ‘StatusCallbackEvents’. Refer here for complete list of parameters which will be sent to your endpoint.
StatusCallbackEvents New Optional

Array; Call events for which we will send details to the URL as set in ‘StatusCallback’ parameter. Can be:

  • terminal - This event will be triggered once the call is terminated (with or without being answered). 
  • answered - This event will be triggered when each leg of the call is answered. One for the caller and one for the callee.

If no event is specified, we will send the default parameters as specified here. Currently, only ‘terminal’ and ‘answered’ event is supported but more events could be added in future.

StatusCallbackContentType New Optional

String; The HTTP header ‘Content-Type’ using which the StatusCallback webhook will be triggered to your URL. Can be:

  • multipart/form-data (default)
  • application/json
curl --location --request POST 'https://api.exotel.com/v1/Accounts/<account_sid>/Calls/connect' \
--header 'Authorization: Basic <Base64_Encoded_APIKey:APIToken>' \
--form 'From="+91XXXXXXXXXX"' \
--form 'To="+91XXXXXXXXXX"' \
--form 'CallerId="XXXXXXXXXX"' \
--form 'StatusCallback="https://yourstatuscallbackurl.com"' \
--form 'StatusCallbackContentType="application/json"' \
--form 'StatusCallbackEvents[0]="terminal"' \
--form 'Record="true"' \
--form 'StatusCallbackEvents[1]="answered"'
var request = require('request');

var dataString = 'From=XXXXX30240&To=XXXXX40682&CallerId=0XXXXXX4890';

var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect',
    method: 'POST',
    body: dataString
};
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();
$data = array(
    'From' => 'XXXXX30240',
    'To' => 'XXXXX40682',
    'CallerId' => '0XXXXXX4890'
);
$response = Requests::post('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect', $headers, $data);
import requests

data = {
  'From': 'XXXXX30240',
  'To': 'XXXXX40682',
  'CallerId': '0XXXXXX4890'
}

requests.post('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect', data=data)
require 'net/http'
require 'uri'

uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect")
request = Net::HTTP::Post.new(uri)
request.set_form_data(
  "From" => "XXXXX30240",
  "To" => "XXXXX40682",
  "CallerId" => "0XXXXXX4890",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
# response.code
# response.body

HTTP Response:

  • On success, the HTTP response status code will be 200. Please note that a 200 OK isn’t a confirmation of a call being successfully placed/answered. Refer to the StatusCallBack or the GET Call Details API to understand the status of the call. 
  • The Sid is the unique identifier of the call, and it will be useful to log this for future debugging
  • the HTTP body will contain an XML/JSON similar to the one below
{
  "Call": {
    "Sid": "c5797dcbaaeed7678c4062a4a3ed2f8a",
    "ParentCallSid": null,
    "DateCreated": "2017-03-03 10:48:33",
    "DateUpdated": "2017-03-03 10:48:33",
    "AccountSid": "Exotel",
    "To": "0XXXXX38847",
    "From": "0XXXXX30240",
    "PhoneNumberSid": "0XXXXXX4890",
    "Status": "in-progress",
    "StartTime": "2017-03-03 10:48:33",
    "EndTime": null,
    "Duration": null,
    "Price": null,
    "Direction": "outbound-api",
    "AnsweredBy": null,
    "ForwardedFrom": null,
    "CallerName": null,
    "Uri": "/v1/Accounts/Exotel/Calls.json/c5797dcbaaeed7678c4062a4a3ed2f8a",
    "RecordingUrl": null
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
    <Call>
        <Sid>06caf2045009d50fbb1da5b5926d2e2f</Sid>
        <ParentCallSid/>
        <DateCreated>2017-03-03 11:00:19</DateCreated>
        <DateUpdated>2017-03-03 11:00:19</DateUpdated>
        <AccountSid>Exotel</AccountSid>
        <To>0XXXXX40682</To>
        <From>0XXXXX30240</From>
        <PhoneNumberSid>0XXXXXX4890</PhoneNumberSid>
        <Status>in-progress</Status>
        <StartTime>2017-03-03 11:00:19</StartTime>
        <EndTime/>
        <Duration/>
        <Price/>
        <Direction>outbound-api</Direction>
        <AnsweredBy/>
        <ForwardedFrom/>
        <CallerName/>
        <Uri>/v1/Accounts/Exotel/Calls/06caf2045009d50fbb1da5b5926d2e2f</Uri>
        <RecordingUrl/>
    </Call>
</TwilioResponse>

Description of parameters mentioned in the above response:

Parameter Name Type & Value
Sid string; an alpha-numeric unique identifier of the call
DateCreated Time in format YYYY-MM-DD HH:mm:ss; Date and time at which the user initiated the API
DateUpdated Time in format YYYY-MM-DD HH:mm:ss; Date and time at which the status of the call was last updated in our system
AccountSid Exotel account SID
To Your customer's phone number
From The phone number that will be called first
PhoneNumberSid This is your ExoPhone/Exotel Virtual Number
Status

Overall call status, which could be one of:

  • queued - The call is ready and waiting in line before going out
  • in-progress - The call was answered and is currently in progress
  • completed - The call was answered and has ended normally
  • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
  • busy - The caller received a busy signal
  • no-answer - The call ended without being answered
StartTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call request was initiated to the operator
EndTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call was completed
Duration Call duration in seconds
Price Double; If present, this will be the amount (in INR or USD) you have been charged for the call
Direction
  • inbound - Incoming call
  • outbound-dial - Outbound calls from Exotel dashboard
  • outbound-api - All other Outbound calls (API, campaign etc.)
AnsweredBy human
Uri Uri is the path of the CallSid
RecordingUrl Link to the call recording

StatusCallback

Exotel will perform an asynchronous HTTP request to the StatusCallback URL you have specified in your request (if any) once the call completes. List of parameters which will be sent as part of StatusCallback:

Parameter Name Type & Value
CallSid string; an alpha-numeric unique identifier of the call
DateUpdated Time in format YYYY-MM-DD HH:mm:ss; Date and time at which the status of the call was last updated in our system
Status Overall call status, which could be one of: 'completed', 'failed', 'busy' or 'no-answer'
RecordingUrl Link to the call recording if present.

List of additional fields which will be sent if 'terminal' and/or ‘answered’ event is subscribed using 'StatusCallbackEvents' in the request:

Parameter Name Type & Value
EventType

String; This will be the type of event for which 'StatusCallback' is triggered for and subscribed using 'StatusCallbackEvents'.

Currently, only ‘terminal’ and ‘answered’ as an event are supported. However, more events can be added in the future.

DateCreated Time in format YYYY-MM-DD HH:mm:ss; Date and time at which the user initiated the API
To Your customer's phone number as set in the API request. This number will be connected after `From`.
From The phone number that was attempted to be called first.
PhoneNumberSid This is your ExoPhone's unique identifier.
StartTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call request was initiated to the operator
EndTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call was completed
ConversationDuration The duration for the time `From` and `To` phone numbers were on call in seconds.
Direction

Can be:

  • inbound - Incoming call
  • outbound-dial - Outbound calls from Exotel dashboard
  • outbound-api - All other Outbound calls (API, campaign etc.)
CustomField The value that was passed in the CustomField parameter of the API (if set during the request) will be populated here.
Legs

An array which will denote detailed information about each leg attempt involved in the call.

  • Legs[i]: `i` denotes the index of the number in order it is attempted. If there are multiple numbers attempted, array’s length will be equal to total attempts. In case of outgoing call connecting two numbers, `i` will be have possible values of 0 and 1. 0th index will represent 'From' leg and 1st index will be represent 'To' leg.
  • OnCallDuration: Indicates the duration that this leg was on a call. This value could be 0 if the call was not picked up by the respective leg.
  • Status: This denotes the terminal status of the particular leg of the call. Can be:
    • completed - The call was answered by the leg.
    • busy - A busy signal was returned by the leg.
    • failed - The call could not be completed as dialled, most likely because the phone number was non-existent.
    • no-answer - The call ended without being answered.
    • canceled - The call was canceled while queued or ringing.
    • null (empty) - The call to that leg was not even attempted.

For understanding more about leg-wise call status, refer here.

Sample:
Legs[0][Status]= “completed”
Legs[0][OnCallDuration]= 29

curl -XPOST https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect \
-d "From=+91941374XXXX" \
-d "To=+91886799XXXX" \
-d "CallerId=0113083XXXX" \
-d "StatusCallback=http://your-application.com/exotel-callback" \
-d "StatusCallbackEvents[0]=terminal" \
-d "StatusCallbackContentType=application/json"
{
  "CallSid": "492205107c5fb48f4ac25d1f77759339",
  "EventType": "terminal",
  "DateCreated": "2019-04-08 03:17:59",
  "DateUpdated": "2019-04-08 03:18:35",
  "Status": "no-answer",
  "To": "+91886799XXXX",
  "From": "+91941374XXXX",
  "PhoneNumberSid": "0113083XXXX",
  "StartTime": "2019-04-08 03:17:59",
  "EndTime": "2019-04-08 03:18:36",
  "Direction": "outbound-api",
  "RecordingUrl": "https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/492205107c5fb48f4ac25d1f77759339.mp3",
  "ConversationDuration": 32,
  "Legs": [
    {
      "OnCallDuration": 41,
      "Status": "completed"
    },
    {
      "OnCallDuration": 32,
      "Status": "completed"
    }
  ]
}
CallSid: 492205107c5fb48f4ac25d1f77759339
EventType: terminal
From: +91941374XXXX
To: +91886799XXXX
PhoneNumberSid: 0113083XXXX
Status: no-answer
Direction: outbound-api
DateCreated: 2019-04-08 03:10:55
DateUpdated: 2019-04-08 03:11:28
StartTime: 2019-04-08 03:10:55
EndTime: 2019-04-08 03:11:30
RecordingUrl:
ConversationDuration: 0
Legs[0][Status]: no-answer
Legs[0][OnCallDuration]: 0
Legs[1][Status]:
Legs[1][OnCallDuration]: 0

Outgoing call to connect number to a call flow

This API will first call the From number, and once they pick up the phone, it will connect them to a call flow (aka applet) that you have created in the system - like your landing app, or any other app that can play a greeting, have IVR, etc. For more details on setting up your flow, please refer Appplet documentation. An HTTP POST request is made to

POST

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect

  • 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

Mandatory/Optional

Value

From

Mandatory

The phone number that will be called first. Preferably in E.164 format. If not set, our system will try to match it with a country and make a call. If landline number, prefix it with STD code; Ex: 0XXXXXX2400

CallerId

Mandatory

This is your ExoPhone (pick one from here)

Url

Mandatory

http://my.exotel.com/{your_sid}/exoml/start_voice/{app_id} where app_id is the identifier of the flow (or applet) that you want to connect to once the From number picks up the call. You can get the app_id from your Exotel Dashboard

CallType

Optional

trans - for Transactional Calls

TimeLimit

Optional

The time limit (in seconds) that you want this call to last. The call will be cut after this time (max. 14400 i.e. 4 hours)

TimeOut

Optional

The time (in seconds) to ring the called parties (both first and second call leg)

StatusCallback

Optional

When the call completes, an HTTP POST will be made to the provided URL with the following four parameters:

  • CallSid - an alpha-numeric unique identifier
  • Status - one of: completed, failed, busy, no-answer
  • RecordingUrl - link to the call recording (if it exists)
  • DateUpdated - time when the call state was updated last

CustomField

Optional

Any application specific value that will be passed back as a parameter while doing a GET request to the URL mentioned in your Passthru Applet or Greetings Applet.

 curl -X POST https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect \
 -d "From=XXXXX30240" \
 -d "CallerId=0XXXXXX4890" \
 -d "Url=http://my.exotel.com/Exotel/exoml/start_voice/926"
var request = require('request');
var dataString = 'From=XXXXX30240&CallerId=0XXXXXX4890&Url=http://my.exotel.com/Exotel/exoml/start_voice/926';
var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect',
    method: 'POST',
    body: dataString
};
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();
$data = array(
    'From' => 'XXXXX30240',
    'CallerId' => '0XXXXXX4890',
    'Url' => 'http://my.exotel.com/Exotel/exoml/start_voice/926'
);
$response = Requests::post('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect', $headers, $data);
import requests

data = {
  'From': 'XXXXX30240',
  'CallerId': '0XXXXXX4890',
  'Url': 'http://my.exotel.com/Exotel/exoml/start_voice/926'
}

requests.post('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect', data=data)
require 'net/http'
require 'uri'

uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect")
request = Net::HTTP::Post.new(uri)
request.set_form_data(
  "From" => "XXXXX30240",
  "CallerId" => "0XXXXXX4890",
  "Url" => "http://my.exotel.com/Exotel/exoml/start_voice/926",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

# response.code
# response.body

HTTP Response:

  • On success, the HTTP response status code will be 200. Please note that a 200 OK isn’t a confirmation of a call being successfully placed/answered. Refer to the StatusCallBack or the GET Call Details API to understand the status of the call.
  • The Sid is the unique identifier of the call, and it will be useful to log this for future debugging
  • the HTTP body will contain an XML similar to the one below
{
  "Call": {
    "Sid": "80bfbec2d78bbbf10fb851f4fa165211",
    "ParentCallSid": null,
    "DateCreated": "2017-03-03 12:30:24",
    "DateUpdated": "2017-03-03 12:30:27",
    "AccountSid": "Exotel",
    "To": "0XXXXX40682",
    "From": "0XXXXX30240",
    "PhoneNumberSid": "0XXXXXX4890",
    "Status": "in-progress",
    "StartTime": "2017-03-03 12:30:27",
    "EndTime": null,
    "Duration": null,
    "Price": null,
    "Direction": "outbound-api",
    "AnsweredBy": null,
    "ForwardedFrom": null,
    "CallerName": null,
    "Uri": "/v1/Accounts/Exotel/Calls.json/80bfbec2d78bbbf10fb851f4fa165211",
    "RecordingUrl": null
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
 <Call>
  <Sid>db05188d0f6cf980cdcef8992c2b8cd4</Sid>
  <ParentCallSid/>
  <DateCreated>2017-02-22 04:35:19</DateCreated>
  <DateUpdated>2017-02-22 04:35:19</DateUpdated>
  <AccountSid>Exotel</AccountSid>
  <To>0XXXXX40682</To>
  <From>0XXXXX30240</From>
  <PhoneNumberSid>0XXXXXX4890</PhoneNumberSid>
  <Status>in-progress</Status>
  <StartTime>2017-02-22 04:35:19</StartTime>
  <EndTime/>
  <Duration/>
  <Price/>
  <Direction>outbound-api</Direction>
  <AnsweredBy/>
  <ForwardedFrom/>
  <CallerName/>
  <Uri>/v1/Accounts/Exotel/Calls/db05188d0f6cf980cdcef8992c2b8cd4</Uri>
  <RecordingUrl/>
 </Call>
</TwilioResponse>

Description of parameters mentioned in the above response:

Parameter Name Type & Value
Sid string; an alpha-numeric unique identifier of the call
DateCreated Time in format YYYY-MM-DD HH:mm:ss; Date and time at which the user initiated the API
DateUpdated Time in format YYYY-MM-DD HH:mm:ss; Date and time at which the status of the call was last updated in our system
AccountSid Exotel account SID
To Your customer's phone number
From The phone number that will be called first
PhoneNumberSid This is your ExoPhone/Exotel Virtual Number
Status

Overall call status, which could be one of:

  • queued - The call is ready and waiting in line before going out
  • in-progress - The call was answered and is currently in progress
  • completed - The call was answered and has ended normally
  • failed - The call could not be completed as dialed, most likely because the phone number was non-existent
  • busy - The caller received a busy signal
  • no-answer - The call ended without being answered
StartTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call request was initiated to the operator
EndTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call was completed
Duration Call duration in seconds
Price Double; If present, this will be the amount (in INR or USD) you have been charged for the call
Direction
  • inbound
  • outbound-dial - Outbound calls from Exotel dashboard
  • outbound-api - All other Outbound calls (API, Campaign etc.)
AnsweredBy human
Uri Uri is the path of the CallSid
RecordingUrl Link to the call recording

Incoming call

When an incoming call lands on your ExoPhone, a call flow is initiated. To configure a call flow for your ExoPhone, please refer Applet documentation.

Bulk Call Details Beta

To get details of calls in bulk (including Status, Price, etc.), you will need to make a HTTP GET request to

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls

  • 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

Description of request query parameters (filters):

Parameter Name Description
Sid

string; an alpha-numeric unique identifier of the call

One or multiple Call SIDs which are comma separated. Recommended limit of SIDs which should be passed together is 20 and maximum allowed limit is 100. If DateCreated is not set, it will only check for last 31 days by default. While querying Sid(s) older than 31 days, DateCreated filter needs to be provided.

 

Example:
/Calls?Sid=48d690c837bb0c755a1228dcb6911416,d7d9cefd9773dd746d8f1e029cdb1417
/Calls?Sid=48d690c837bb0c755a1228dcb6911416&DateCreated=gte:2019-01-01 00:00:00;lte:2019-01-31 23:59:59

DateCreated Date and time at which the Call resource was created in the Exotel system. Supported operators (gte and lte), for more info refer to filter operators section below. You can query call records only up to 6 months old and provide maximum date range of 1 month.

Default if not set: Last 31 days

Example:
/Calls?DateCreated=gte:2019-01-01 00:00:00;lte:2019-01-31 23:59:59
To Your customer's phone number. One or multiple To numbers can be provided (in E.164 format) which are comma separated. (max limit: 5)

Example:
/Calls?To=<number-1>
/Calls?To=<number-1>,<number-2>"
From The phone number that will be called first. One or multiple From numbers can be provided (in E.164 format) which are comma separated. (max limit: 5)

Example:
/Calls?From=<number-1>
/Calls?From=<number-1>,<number-2>,...
Status

Overall call status, which could be one of:

  • completed - The call was answered and has ended normally
  • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
  • busy - The caller received a busy signal
  • no-answer - The call ended without being answered

Example:
/Calls?Status=completed
/Calls?Status=failed,no-answer,busy,canceled

Duration Call duration in seconds. Supported operators (gte, eq and lte), for more info refer to filter operators section below.

Example:
/Calls?Duration=gte:10s;lte:45s
/Calls?Duration=eq:30s
Price If present, this will be the amount (as per your billing currency) you have been charged for the call. Supported operators (gte, eq and lte), for more info refer to filter operators section below.

Example:
/Calls?Price=gte:0.10;lte:1.0
/Calls?Price=eq:0.300030
Direction
  • inbound
  • outbound-dial - Outbound calls from Exotel dashboard
  • outbound-api - All other Outbound calls (API, campaign etc.)

Example:
/Calls?Direction=inbound
/Calls?Direction=outbound-dial,inbound

PhoneNumber This represents the Virtual Number (ExoPhone) used for the call. One or multiple PhoneNumber(s) can be provided (in E.164 format) which are comma separated. (max limit: 5)

Example:
/Calls?PhoneNumber=<vn-1>
/Calls?PhoneNumber=<vn-1>,<vn-2>,...
PageSize This represents number of records visible in one page of the API response. Default: 50, Max: 100
SortBy This indicates in what order the Call records are sorted in the API response. By default records are sorted by DateCreated in descending order. However, you can override the same in following way for ascending order:

Example:
/Calls?SortBy=DateCreated:asc
Before Auto generated unique string returned in the PrevPageUri (under Metadata) to be used as query param when at least one record is returned in that page. The value of this field is a cursor which identifies a call record uniquely.
After Auto generated unique string returned in the NextPageUri (under Metadata) to be used as query param when at least one record is present in that page. The value of this field is a cursor which identifies a call record uniquely.

Filter Operators (Please note these operators are only applicable to certain query parameters as mentioned above)

Operator

Description

Examples

eq:

Equals

Return results where duration is exactly ten seconds:

Duration=eq:10s

Same can also be written as Duration=10s

gte:

Greater than or equal to

Return results where Duration is ten seconds or more:

Duration=gte:10s

lte:

Less than or equal to

Return results where Duration is ten seconds or less:

Duration=lte:10s

,

OR operator

OR operator (,) is used to select multiple values if any one of them matches

;

AND operator

AND operator (;) is used to select multiple values if all of them matches. Url encode ; to %3B while making the API request.

 

curl https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls
 
var request = require('request');

var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls'
};

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>/Calls', $headers);
import requests

requests.get('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls')
require 'net/http'
require 'uri'

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

# response.code
# response.body

HTTP Response:

  • On success, the HTTP response status code will be 200
  • the HTTP response body will contain an JSON/XML similar to the one below
{
    "Metadata": {
        "Total": 1027,
        "PageSize": 1,
        "FirstPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc",
        "PrevPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&Before=MTU3Nzk4NjAwNixhZmQ4MGJhNzI1MzA5YmU2MjM0MTA2YjY5ZGVmMTQxMg==",
        "NextPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&After=MTU3Nzk4NDQwNywwNmQ4ZmI0MDdlZWY5N2YxZmI0OTllNjZjOTI5MTQxMg=="
    },
    "Calls": [
        {
            "Sid": "b6cfaf5f5cef3ca0fc937749ef960e25",
            "ParentCallSid": "",
            "DateCreated": "2016-11-29 15:58:45",
            "DateUpdated": "2016-11-29 16:00:09",
            "AccountSid": "Exotel",
            "To": "0XXXXX20000",
            "From": "0XXXXX30240",
            "PhoneNumberSid": "0XXXXXX4890",
            "Status": "completed",
            "StartTime": "2016-11-29 15:59:10",
            "EndTime": "2016-11-29 15:59:27",
            "Duration": "17",
            "Price": "1.500",
            "Direction": "outbound-api",
            "AnsweredBy": "human",
            "ForwardedFrom": "",
            "CallerName": "",
            "Uri": "/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25",
            "RecordingUrl": "https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/b6cfaf5f5cef3ca0fc937749ef960e25.mp3"
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
    <Metadata>
        <Total>1027</Total>
        <PageSize>1</PageSize>
        <FirstPageUri>/v1/Accounts/Exotel/Calls?PageSize=2&amp;DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&amp;SortBy=DateCreated:desc</FirstPageUri>
        <PrevPageUri>/v1/Accounts/Exotel/Calls?PageSize=2&amp;DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&amp;SortBy=DateCreated:desc&amp;Before=MTU3Nzk4NjAwNixhZmQ4MGJhNzI1MzA5YmU2MjM0MTA2YjY5ZGVmMTQxMg==</PrevPageUri>
        <NextPageUri>/v1/Accounts/Exotel/Calls?PageSize=2&amp;DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&amp;SortBy=DateCreated:desc&amp;After=MTU3Nzk4NDQwNywwNmQ4ZmI0MDdlZWY5N2YxZmI0OTllNjZjOTI5MTQxMg==</NextPageUri>
    </Metadata>
 <Call>
  <Sid>b6cfaf5f5cef3ca0fc937749ef960e25</Sid>
  <ParentCallSid></ParentCallSid>
  <DateCreated>2017-02-17 14:16:03</DateCreated>
  <DateUpdated>2017-02-17 14:17:32</DateUpdated>
  <AccountSid>Exotel</AccountSid>
  <To>0XXXXX20000</To>
  <From>0XXXXX30240</From>
  <PhoneNumberSid>0XXXXXX4890</PhoneNumberSid>
  <Status>completed</Status>
  <StartTime>2017-02-17 14:16:03</StartTime>
  <EndTime>2017-02-17 14:16:20</EndTime>
  <Duration>17</Duration>
  <Price>0.750</Price>
  <Direction>inbound</Direction>
  <AnsweredBy>human</AnsweredBy>
  <ForwardedFrom></ForwardedFrom>
  <CallerName></CallerName>
  <Uri>/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25</Uri>
  <RecordingUrl>https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/b6cfaf5f5cef3ca0fc937749ef960e25.mp3</RecordingUrl>
 </Call>
</TwilioResponse>

Description of parameters under 'Metadata' object mentioned in the above response:

Parameter Name Type & Value
Total Number of call records matching the given query and filters at that point of time
PageSize This indicates the number of records on that page
FirstPageUri This indicates the URI of the first page as per the request. This can be used to to retrieve call records from the beginning of the page.
PrevPageUri This indicates the URI of the previous page as per the request. This can be used to to retrieve previous set of call records.
NextPageUri This indicates the URI of the next page as per the request. This can be used to to retrieve next set of call records.


Description of parameters under 'Calls' array object mentioned in the above response:

Parameter Name Type & Value
Sid string; an alpha-numeric unique identifier of the call
DateCreated Date and time at which the user initiated the API
DateUpdated Date and time at which the status of the call was last updated in our system
AccountSid Your account SID
To Your customer's phone number in E.164 format 
From The phone number that will be called first in E.164 format
PhoneNumber This is your ExoPhone/Exotel Virtual Number in E.164 format
PhoneNumberSid This is the SID (unique ID)of the ExoPhone/Exotel Virtual Number. It can be same as the ExoPhone number or UUID based on when your number was configured.
Status

Overall call status, which could be one of:

  • completed - The call was answered and has ended normally
  • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
  • busy - The caller received a busy signal
  • no-answer - The call ended without being answered
StartTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call request was initiated to the operator
EndTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call was completed
Duration Call duration in seconds
Price Double; If present, this will be the amount (in INR or USD) you have been charged for the call
Direction
  • inbound
  • outbound-dial - Outbound calls from Exotel dashboard
  • outbound-api - All other Outbound calls (API, campaign etc.)
AnsweredBy human
Uri Uri is the path of the CallSid
RecordingUrl Link to the call recording

If additional information such as status of both the call legs are required, you will need to make an HTTP GET request as:

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls?details=true

HTTP Response:

  • On success, the HTTP response status code will be 200
  • the HTTP body will contain an XML similar to the one below
{
    "Metadata": {
        "Total": 1027,
        "PageSize": 1,
        "FirstPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&details=true",
        "PrevPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&details=true&amp;Before=MTU3Nzk4NjAwNixhZmQ4MGJhNzI1MzA5YmU2MjM0MTA2YjY5ZGVmMTQxMg==",
        "NextPageUri": "/v1/Accounts/<your_sid>/Calls.json?PageSize=2&DateCreated=gte%3A2020-01-01+00%3A00%3A00%3Blte%3A2020-01-03+00%3A00%3A00&SortBy=DateCreated:desc&details=true&After=MTU3Nzk4NDQwNywwNmQ4ZmI0MDdlZWY5N2YxZmI0OTllNjZjOTI5MTQxMg=="
    },
    "Calls": [
        {
            "Sid": "b6cfaf5f5cef3ca0fc937749ef960e25",
            "ParentCallSid": "",
            "DateCreated": "2016-11-29 15:58:45",
            "DateUpdated": "2016-11-29 16:00:09",
            "AccountSid": "Exotel",
            "To": "0XXXXX20000",
            "From": "0XXXXX30240",
            "PhoneNumberSid": "0XXXXXX4890",
            "Status": "completed",
            "StartTime": "2016-11-29 15:59:10",
            "EndTime": "2016-11-29 15:59:57",
            "Duration": "47",
            "Price": "1.500",
            "Direction": "outbound-api",
            "AnsweredBy": "human",
            "ForwardedFrom": "",
            "CallerName": "",
            "Uri": "/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25",
            "RecordingUrl": "https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/b6cfaf5f5cef3ca0fc937749ef960e25.mp3",
            "Details": {
                "ConversationDuration": 33,
                "Legs": [
                    {
                        "Leg": {
                            "Id": 1,
                            "OnCallDuration": 43
                        }
                    },
                    {
                        "Leg": {
                            "Id": 2,
                            "OnCallDuration": 33
                        }
                    }
                ],
                "Leg1Status": "completed",
                "Leg2Status": "no-answer"
            }
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
    <Metadata>
        <Total>1027</Total>
        <PageSize>1</PageSize>
        <FirstPageUri>/v1/Accounts/Exotel/Calls?PageSize=100&amp;SortBy=DateCreated:desc&amp;Status=completed&amp;details=true&amp;NumbersMetadata=true</FirstPageUri>
        <PrevPageUri>/v1/Accounts/Exotel/Calls?PageSize=100&amp;SortBy=DateCreated:desc&amp;Status=completed&amp;details=true&amp;NumbersMetadata=true&amp;Before=MTU3ODUwMjgwMyxiNTM2MzgzNzZlZWMyYTUxNjVmZGVlZmU2OWQyMTQxOA==</PrevPageUri>
        <NextPageUri>/v1/Accounts/Exotel/Calls?PageSize=100&amp;SortBy=DateCreated:desc&amp;Status=completed&amp;details=true&amp;NumbersMetadata=true&amp;After=MTU3ODQ4NTE2OSwwNjYwMDJiOWE2MmZiN2IxMmE0YjljODAzNTZmMTQxOA==</NextPageUri>
    </Metadata>
    <Call>
        <Sid>b6cfaf5f5cef3ca0fc937749ef96d245</Sid>
        <ParentCallSid></ParentCallSid>
        <DateCreated>2016-11-29 15:58:45</DateCreated>
        <DateUpdated>2016-11-29 16:00:09</DateUpdated>
        <AccountSid>Exotel</AccountSid>
        <To>0XXXXX30240</To>
        <From>0XXXXX85175</From>
        <PhoneNumberSid>0XXXXXX4890</PhoneNumberSid>
        <Status>completed</Status>
        <StartTime>2016-11-29 15:59:10</StartTime>
        <EndTime>2016-11-29 15:59:27</EndTime>
        <Duration>17</Duration>
        <Price>1.500</Price>
        <Direction>outbound-api</Direction>
        <AnsweredBy>human</AnsweredBy>
        <ForwardedFrom></ForwardedFrom>
        <CallerName></CallerName>
        <Uri>/v1/Accounts/Exotel/Calls/b6cfaf5f5cef3ca0fc937749ef96d245</Uri>
        <RecordingUrl>https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/Exotel/b6cfaf5f5cef3ca0fc937749ef96d245.mp3</RecordingUrl>
        <Details>
            <ConversationDuration>8</ConversationDuration>
            <Leg1Status>completed</Leg1Status>
            <Leg2Status>completed</Leg2Status>
            <Legs>
                <Leg>
                    <Id>1</Id>
                    <OnCallDuration>21</OnCallDuration>
                </Leg>
                <Leg>
                    <Id>2</Id>
                    <OnCallDuration>8</OnCallDuration>
                </Leg>
            </Legs>
        </Details>
    </Call>
</TwilioResponse>

Description of parameters under "Details" mentioned in the above response:

Parameter Name Value
ConversationDuration The duration for the From and To phone numbers on call in seconds
Leg1Status

Status of the first leg of the call. Can be one of

  • completed - The call was answered and has ended normally
  • busy - The caller received a busy signal
  • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
  • no-answer - The call ended without being answered
  • canceled - The call was canceled while queued or ringing
Leg2Status

Status of the second leg of the call. Can be one of

  • completed - The call was answered and has ended normally
  • busy - The caller received a busy signal
  • no-answer - The call ended without being answered
  • failed - The call could not be completed as dialed, most likely because the phone number was non-existent
  • canceled - The call was canceled while queued or ringing
  • null (empty) - The call did not have a second leg
Legs

Status of individual legs of the call. Contains the following information (per leg) in an array:

  • Id - Indicates the leg. Can be 1 or 2.
  • OnCallDuration - Indicates the duration that this leg was on a call.

The following are few examples in which API can be requested depending on the use-case:

Calls filtered by DateCreated range with Leg-wise details and Page Size = 100

GET

https://<subdomain>/v1/Accounts/<your_sid>/Calls.json?DateCreated=gte:2019-12-03+00:00:00%3Blte:2019-12-04+00:00:00&details=true&PageSize=100

Get all Incoming calls received by an agent (To number) for a given date range

GET

https://<subdomain>/v1/Accounts/<your_sid>/Calls.json?DateCreated=gte:2019-12-03+00:00:00%3Blte:2019-12-04+00:00:00&To=%2B91xxxxxxxxxx

Calls with Duration greater than 10 seconds and less than 60 seconds

GET

https://<subdomain>/v1/Accounts/<your_sid>/Calls.json?DateCreated=gte:2019-12-03+00:00:00%3Blte:2019-12-04+00:00:00&Duration=gte:11s%3Blte:59s

Calls which are failed and having ExoPhone (Virtual Phone Number) as +91xxxxxxxxxx

GET

https://<subdomain>/v1/Accounts/<your_sid>/Calls.json?DateCreated=gte:2019-12-03+00:00:00%3Blte:2019-12-04+00:00:00&Status=failed&PhoneNumber=%2B91xxxxxxxxxx


Number Metadata

This API provides the following metadata about a phone number:

  • Telecom Circle
  • Telecom Circle Name
  • Number Type
  • Whether the number belongs to DND or not

To get the above information you need to make a HTTP GET request to

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Numbers/~number~

  • 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>/Numbers/XXXXX30240 
      
var request = require('request');

var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Numbers/XXXXX30240'
};

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>/Numbers/XXXXX30240', $headers);
import requests

requests.get('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Numbers/XXXXX30240')
require 'net/http'
require 'uri'

uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Numbers/XXXXX30240")
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
{
  "Numbers": {
    "PhoneNumber": "0XXXXX30240",
    "Circle": "GJ",
    "CircleName": "Gujarat Telecom Circle (includes Daman & Diu, Dadra & Nagar Haveli)",
    "Type": "Mobile",
    "Operator": "R",
    "OperatorName": "Reliance",
    "DND": "Yes"
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
 <Numbers>
  <PhoneNumber>0XXXXX30240</PhoneNumber>
  <Circle>GJ</Circle>
  <CircleName>Gujarat Telecom Circle (includes Daman &amp; Diu, Dadra &amp; Nagar Haveli)</CircleName>
  <Type>Mobile</Type>
  <Operator>R</Operator>
  <OperatorName>Reliance</OperatorName>
  <DND>Yes</DND>
 </Numbers>
</TwilioResponse>

Description of parameters mentioned in the above response:

Parameter Name Type & Value
PhoneNumber string; Reformatted phone number
Circle Two character telecom circle code. Refer below table for more details
CircleName Human readable string of the Circle code. Ex: Haryana Telecom Circle (excludes Faridabad, Gurgaon & Panchkula)
Type 'Mobile' or 'Landline'
Operator Single or two character telecom operator code. Refer below table for more details
OperatorName Telecom operator to which the number belongs
DND
  • Yes
  • No
  • Unavailable

Description of all the telecom circles in India:

Circle Name Value
AP Andhra Pradesh Telecom Circle
AS Assam Telecom Circle
BR Bihar & Jharkhand Telecom Circle
CH Chennai Metro Telecom Circle (includes Chennai, MEPZ & Mahabalipuram)
DL Delhi Metro Telecom Circle (includes NCR, Faridabad, Ghaziabad, Gurgaon & Noida)
GJ Gujarat Telecom Circle (includes Daman & Diu, Dadra & Nagar Haveli)
HP Himachal Pradesh Telecom Circle
HR Haryana Telecom Circle (excludes Faridabad, Gurgaon & Panchkula)
JK Jammu & Kashmir Telecom Circle
KL Kerala Telecom Circle (includes Lakshadeep)
KA Karnataka Telecom Circle
KO Kolkata Metro Telecom Circle (includes parts of Haora, Hooghly, North & South 24 Parganas and Nadia Districts)
MH Maharashtra Telecom Circle (includes Goa but excludes Mumbai, Navi Mumbai & Kalyan)
MP Madhya Pradesh & Chhattisgarh Telecom Circle
MU Mumbai Metro Telecom Circle (includes Navi Mumbai & Kalyan)
NE North East India Telecom Circle (includes Arunachal Pradesh, Meghalaya, Mizoram, Nagaland, Manipur & Tripura)
OR Orissa Telecom Circle
PB Punjab Telecom Circle (includes Chandigarh & Panchkula)
RJ Rajasthan Telecom Circle
TN Tamil Nadu Telecom Circle (excludes CH Chennai, MEPZ, Mahabalipuram & Minjur and includes Pondicherry except Yanam & Mahe)
UE Uttar Pradesh (East) Telecom Circle
UW Uttar Pradesh (West) & Uttarakhand Telecom Circle (excludes Ghaziabad & Noida)
WB West Bengal Telecom Circle (includes Andaman & Nicobar,Sikkim excludes Calcutta Telecom District)
AN Andaman & Nicobar
BY Mumbai Metro Telecom Circle (includes Navi Mumbai & Kalyan)
HA Haryana Telecom Circle (excludes Faridabad, Gurgaon & Panchkula)
ND Delhi Metro Telecom Circle (includes NCR, Faridabad, Ghaziabad, Gurgaon & Noida)
UPE Uttar Pradesh (East) Telecom Circle
UPW Uttar Pradesh (West) & Uttarakhand Telecom Circle (excludes Ghaziabad & Noida)

Description of Telecom operators in India:

Operator Name Value
AC Aircel
A Airtel
AL Allianz
B BSNL
D Dishnet
E Etisalat
H HFCL
I Idea
LO Loop
MT MTNL
P Ping
R Reliance
S Sistema
ST S Tel
T Tata
U Unitech
VI Videocon
V Vodafone

Call Details

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

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/<CallSid>

Where <CallSid> is an alpha-numeric unique identifier generated for all the calls made 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

In the case of an outbound call originated via the API, the Sid parameter is as returned in the XML/JSON response to your request. In the case of inbound calls, you can get the Sid by using the Passthru applet.

curl https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25
 
var request = require('request');

var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25'
};

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>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25', $headers);
import requests

requests.get('https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25')
require 'net/http'
require 'uri'

uri = URI.parse("https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25")
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
{
  "Call": {
    "Sid": "b6cfaf5f5cef3ca0fc937749ef960e25",
    "ParentCallSid": "",
    "DateCreated": "2016-11-29 15:58:45",
    "DateUpdated": "2016-11-29 16:00:09",
    "AccountSid": "Exotel",
    "To": "0XXXXX20000",
    "From": "0XXXXX30240",
    "PhoneNumberSid": "0XXXXXX4890",
    "Status": "completed",
    "StartTime": "2016-11-29 15:59:10",
    "EndTime": "2016-11-29 15:59:27",
    "Duration": "17",
    "Price": "1.500",
    "Direction": "outbound-api",
    "AnsweredBy": "human",
    "ForwardedFrom": "",
    "CallerName": "",
    "Uri": "/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25",
    "RecordingUrl": "https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/b6cfaf5f5cef3ca0fc937749ef960e25.mp3"
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
 <Call>
  <Sid>b6cfaf5f5cef3ca0fc937749ef960e25</Sid>
  <ParentCallSid></ParentCallSid>
  <DateCreated>2017-02-17 14:16:03</DateCreated>
  <DateUpdated>2017-02-17 14:17:32</DateUpdated>
  <AccountSid>Exotel</AccountSid>
  <To>0XXXXX20000</To>
  <From>0XXXXX30240</From>
  <PhoneNumberSid>0XXXXXX4890</PhoneNumberSid>
  <Status>completed</Status>
  <StartTime>2017-02-17 14:16:03</StartTime>
  <EndTime>2017-02-17 14:16:20</EndTime>
  <Duration>17</Duration>
  <Price>0.750</Price>
  <Direction>inbound</Direction>
  <AnsweredBy>human</AnsweredBy>
  <ForwardedFrom></ForwardedFrom>
  <CallerName></CallerName>
  <Uri>/v1/Accounts/<your_sid>/Calls/b6cfaf5f5cef3ca0fc937749ef960e25</Uri>
  <RecordingUrl>https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/b6cfaf5f5cef3ca0fc937749ef960e25.mp3</RecordingUrl>
 </Call>
</TwilioResponse>

Description of parameters mentioned in the above response:

Parameter Name Type & Value
Sid string; an alpha-numeric unique identifier of the call
DateCreated Date and time at which the user initiated the API
DateUpdated Date and time at which the status of the call was last updated in our system
AccountSid Your account SID
To Your customer's phone number
From The phone number that will be called first
PhoneNumberSid This is your ExoPhone/Exotel Virtual Number
Status

Overall call status, which could be one of:

  • queued - The call is ready and waiting in line before going out
  • ringing - The call is currently in-flight
  • in-progress - The call was answered and is currently in progress
  • completed - The call was answered and has ended normally
  • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
  • busy - The caller received a busy signal
  • no-answer - The call ended without being answered
StartTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call request was initiated to the operator
EndTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call was completed
Duration Call duration in seconds
Price Double; If present, this will be the amount (in INR or USD) you have been charged for the call
Direction
  • inbound
  • outbound-dial - Outbound calls from Exotel dashboard
  • outbound-api - All other Outbound calls (API, campaign etc.)
AnsweredBy human
Uri Uri is the path of the CallSid
RecordingUrl Link to the call recording

If status of both the call legs are required incase of an outbound call, you will need to make an HTTP GET request to

GET

https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/<CallSid>?details=true

HTTP Response:

  • On success, the HTTP response status code will be 200
  • the HTTP body will contain an XML similar to the one below
{
  "Call": {
    "Sid": "b6cfaf5f5cef3ca0fc937749ef96d245",
    "ParentCallSid": "",
    "DateCreated": "2016-11-29 15:58:45",
    "DateUpdated": "2016-11-29 16:00:09",
    "AccountSid": "Exotel",
    "To": "0XXXXX30240",
    "From": "0XXXXX85175",
    "PhoneNumberSid": "0XXXXXX4890",
    "Status": "completed",
    "StartTime": "2016-11-29 15:59:10",
    "EndTime": "2016-11-29 15:59:27",
    "Duration": "17",
    "Price": "1.500",
    "Direction": "outbound-api",
    "AnsweredBy": "human",
    "ForwardedFrom": "",
    "CallerName": "",
    "Uri": "/v1/Accounts/Exotel/Calls/b6cfaf5f5cef3ca0fc937749ef96d245",
    "RecordingUrl": "https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/Exotel/b6cfaf5f5cef3ca0fc937749ef96d245.mp3",
    "Details": {
      "ConversationDuration": 8,
      "Leg1Status": "completed",
      "Leg2Status": "completed"
      "Legs": [
        {    "Leg": {
              "Id": "1",
              "OnCallDuration": 21
             }
        },
        {    "Leg": {
             "Id": "2",
             "OnCallDuration": 8
             }
        }
      ]
    }
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
    <Call>
        <Sid>b6cfaf5f5cef3ca0fc937749ef96d245</Sid>
        <ParentCallSid></ParentCallSid>
        <DateCreated>2016-11-29 15:58:45</DateCreated>
        <DateUpdated>2016-11-29 16:00:09</DateUpdated>
        <AccountSid>Exotel</AccountSid>
        <To>0XXXXX30240</To>
        <From>0XXXXX85175</From>
        <PhoneNumberSid>0XXXXXX4890</PhoneNumberSid>
        <Status>completed</Status>
        <StartTime>2016-11-29 15:59:10</StartTime>
        <EndTime>2016-11-29 15:59:27</EndTime>
        <Duration>17</Duration>
        <Price>1.500</Price>
        <Direction>outbound-api</Direction>
        <AnsweredBy>human</AnsweredBy>
        <ForwardedFrom></ForwardedFrom>
        <CallerName></CallerName>
        <Uri>/v1/Accounts/Exotel/Calls/b6cfaf5f5cef3ca0fc937749ef96d245</Uri>
        <RecordingUrl>https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/Exotel/b6cfaf5f5cef3ca0fc937749ef96d245.mp3</RecordingUrl>
        <Details>
            <ConversationDuration>8</ConversationDuration>
            <Leg1Status>completed</Leg1Status>
            <Leg2Status>completed</Leg2Status>
            <Legs>
                <Leg>
                    <Id>1</Id>
                    <OnCallDuration>21</OnCallDuration>
                </Leg>
                <Leg>
                    <Id>2</Id>
                    <OnCallDuration>8</OnCallDuration>
                </Leg>
            </Legs>
        </Details>
    </Call>
</TwilioResponse>

Description of parameters mentioned in the above response:

Parameter Name Value
ConversationDuration The duration for the From and To phone numbers on call in seconds
Leg1Status

Status of the first leg of the call. Can be one of

  • queued - The call is ready and waiting in line before going out
  • ringing - The call is currently in-flight
  • in-progress - The call was answered and is currently in progress
  • completed - The call was answered and has ended normally
  • busy - The caller received a busy signal
  • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
  • no-answer - The call ended without being answered
  • canceled - The call was canceled while queued or ringing
Leg2Status

Status of the second leg of the call. Can be one of

  • completed - The call was answered and has ended normally
  • busy - The caller received a busy signal
  • no-answer - The call ended without being answered
  • failed - The call could not be completed as dialed, most likely because the phone number was non-existent
  • canceled - The call was canceled while queued or ringing
  • null (empty) - The call did not have a second leg
Legs

Status of individual legs of the call. Contains the following information (per leg):

  • Id - Indicates the leg. Can be 1 or 2.
  • OnCallDuration - Indicates the duration that this leg was on a call (see below for more information on how this is calculated).

The following diagram illustrates how the call duration is calculated for a call and its constituent legs.


StatusCallback

Exotel will perform an asynchronous HTTP request to the StatusCallback URL you have specified in your request (if any) once the call completes. List of parameters which will be sent as part of StatusCallback:

Parameter Name Type & Value
CallSid string; an alpha-numeric unique identifier of the call
DateUpdated Time in format YYYY-MM-DD HH:mm:ss; Date and time at which the status of the call was last updated in our system
Status Overall call status, which could be one of: 'completed', 'failed', 'busy' or 'no-answer'
RecordingUrl Link to the call recording if present.

List of additional fields which will be sent if 'terminal' and/or ‘answered’ event is subscribed using 'StatusCallbackEvents' in the request:

Parameter Name Type & Value
EventType

String; This will be the type of event for which 'StatusCallback' is triggered for and subscribed using 'StatusCallbackEvents'.

Currently, only ‘terminal’ and ‘answered’ as an event is supported which is triggered once the call is over. However, more events can be added in the future.

DateCreated Time in format YYYY-MM-DD HH:mm:ss; Date and time at which the user initiated the API
To Your customer's phone number as set in the API request. This number will be connected after `From`.
From The phone number that was attempted to be called first.
PhoneNumberSid This is your ExoPhone's unique identifier.
StartTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call request was initiated to the operator
EndTime Time in format YYYY-MM-DD HH:mm:ss; Date and time when the call was completed
ConversationDuration The duration for the time `From` and `To` phone numbers were on call in seconds.
Direction

Can be:

  • inbound - Incoming call
  • outbound-dial - Outbound calls from Exotel dashboard
  • outbound-api - All other Outbound calls (API, campaign etc.)
CustomField The value that was passed in the CustomField parameter of the API (if set during the request) will be populated here.
Legs

An array which will denote detailed information about each leg attempt involved in the call.

  • Legs[i]: `i` denotes the index of the number in order it is attempted. If there are multiple numbers attempted, array’s length will be equal to total attempts. In case of outgoing call connecting two numbers, `i` will be have possible values of 0 and 1. 0th index will represent 'From' leg and 1st index will be represent 'To' leg.
  • OnCallDuration: Indicates the duration that this leg was on a call. This value could be 0 if the call was not picked up by the respective leg.
  • Status: This denotes the terminal status of the particular leg of the call. Can be:
    • completed - The call was answered by the leg.
    • busy - A busy signal was returned by the leg.
    • failed - The call could not be completed as dialled, most likely because the phone number was non-existent.
    • no-answer - The call ended without being answered.
    • canceled - The call was canceled while queued or ringing.
    • null (empty) - The call to that leg was not even attempted.

For understanding more about leg-wise call status, refer here.

Sample:
Legs[0][Status]= “completed”
Legs[0][OnCallDuration]= 29

curl -XPOST https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect \
-d "From=+91941374XXXX" \
-d "To=+91886799XXXX" \
-d "CallerId=0113083XXXX" \
-d "StatusCallback=http://your-application.com/exotel-callback" \
-d "StatusCallbackEvents[0]=terminal" \
-d "StatusCallbackContentType=application/json"
{
  "CallSid": "492205107c5fb48f4ac25d1f77759339",
  "EventType": "terminal",
  "DateCreated": "2019-04-08 03:17:59",
  "DateUpdated": "2019-04-08 03:18:35",
  "Status": "no-answer",
  "To": "+91886799XXXX",
  "From": "+91941374XXXX",
  "PhoneNumberSid": "0113083XXXX",
  "StartTime": "2019-04-08 03:17:59",
  "EndTime": "2019-04-08 03:18:36",
  "Direction": "outbound-api",
  "RecordingUrl": "https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/<your_sid>/492205107c5fb48f4ac25d1f77759339.mp3",
  "ConversationDuration": 32,
  "Legs": [
    {
      "OnCallDuration": 41,
      "Status": "completed"
    },
    {
      "OnCallDuration": 32,
      "Status": "completed"
    }
  ]
}
CallSid: 492205107c5fb48f4ac25d1f77759339
EventType: terminal
From: +91941374XXXX
To: +91886799XXXX
PhoneNumberSid: 0113083XXXX
Status: no-answer
Direction: outbound-api
DateCreated: 2019-04-08 03:10:55
DateUpdated: 2019-04-08 03:11:28
StartTime: 2019-04-08 03:10:55
EndTime: 2019-04-08 03:11:30
RecordingUrl:
ConversationDuration: 0
Legs[0][Status]: no-answer
Legs[0][OnCallDuration]: 0
Legs[1][Status]:
Legs[1][OnCallDuration]: 0