×

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