×

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
  • Example Request (using StatusCallback):
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