Voice v1 APIs work without any user (call centre agent) context, i.e. they don’t need a user to be added to the Exotel dashboard and therefore don’t check a user number for busy status before calling that number.
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
https://<your_api_key>:<your_api_token><subdomain>/v1/Accounts/<your_sid>/Calls/connect
If you’d prefer response in JSON format, just append .json at the end of the HTTP POST request.
Replace <your_api_key>
and <your_api_token>
with the API key and token created by you.
<your_sid>
with your “Account sid”<subdomain>
with the region of your account<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:
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:
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
|
RecordingFormat | Optional |
String; Quality of the audio recording. This parameter works if
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:
|
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 |
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:
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:
|
If you would like to use streaming via this API, please contact hello@exotel.in
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:
{ "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:
|
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 |
|
AnsweredBy | human |
Uri | Uri is the path of the CallSid |
RecordingUrl | Link to the call recording |
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:
|
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.
For understanding more about leg-wise call status, refer here. Sample: |
Additional StatusCallback fields are currently only supported if both ‘From’ and ‘To’ are set. StatusCallbackEvents parameter is not applicable for this case i.e. if ‘VoiceUrl’ is used. However, passthru applet can be utilised if ‘VoiceUrl’ is used.
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