Connect Two Numbers
Make an outbound call that connects two phone numbers. The platform calls the From number first, and once they answer, the To number is dialed and connected.
Request Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
From | Yes | String | The number called first. Accepts an E.164 phone number (e.g., +919900XXXXXX) or a SIP URI (e.g., sip:agent@exotel.com). |
To | Yes | String | Customer phone number. E.164 format only (e.g., +918800XXXXXX). |
CallerId | Yes | String | Your ExoPhone/virtual number. |
CallType | No | String | trans for transactional calls. |
TimeLimit | No | Integer | Max call duration in seconds. Max: 14400 (4 hours). |
TimeOut | No | Integer | Time in seconds to ring the called parties (both the From and To legs). The timer runs only during ringing and stops once each leg is answered. |
WaitUrl | No | String | Audio URL (WAV) played while waiting. Recommended: under 2MB. |
Record | No | Boolean | true to record the conversation. |
RecordingChannels | No | String | single (default) or dual. |
RecordingFormat | No | String | mp3 (default) or mp3-hq. |
StreamUrl | No | String | WebSocket URL for real-time audio streaming. |
StreamBegin | No | String | at Leg1Connect or at Leg2Connect. |
CustomField | No | String | Metadata (max 128 chars). Passed to StatusCallback and applets. |
StartPlaybackToNew | No | String | Callee (default) or Both. |
StartPlaybackValueNew | No | String | Audio URL for pre-call playback. |
StatusCallback | No | String | Webhook URL for call status updates. |
StatusCallbackEvents | No | Array | terminal, answered, or both. |
StatusCallbackContentType | No | String | multipart/form-data (default) or application/json. Applies to both StatusCallback and AsyncAmdStatusCallback. |
MachineDetection | No | String | Enable answering machine detection: Enable or Disable (default). Case-insensitive. Omitting the parameter is treated as Disable. Empty string is invalid and returns 400. |
AsyncAmd | No | String | Required when MachineDetection=Enable. Must be true. Any other value returns 400. Synchronous AMD is not supported. |
AsyncAmdStatusCallback | No | String | Required when AsyncAmd=true. Absolute http or https URL to receive the AMD result. Hostnames with underscores are rejected. |
Answering Machine Detection
When MachineDetection=Enable, the platform runs AMD in parallel with the call after Leg 1 (the From leg) answers. It does not auto-hangup. Your server receives the result at AsyncAmdStatusCallback and decides whether to hang up.
Validation rules
| Condition | Result |
|---|---|
MachineDetection omitted | Treated as Disable; AMD params ignored |
MachineDetection=Disable | AMD params present but ignored; no 400 |
MachineDetection=Enable, valid AsyncAmd=true and AsyncAmdStatusCallback | AMD enabled |
MachineDetection=Enable, missing or invalid AsyncAmd or AsyncAmdStatusCallback | 400 |
MachineDetection= (empty string) | 400 |
AsyncAmdStatusCallback payload
Exotel POSTs to your URL when AMD completes. This fires even if the call has already ended.
| Field | Type | Description |
|---|---|---|
CallSid | String | Call SID |
AccountSid | String | Account SID |
AnsweredBy | String | HUMAN, MACHINE, or NOTSURE |
AmdCause | String | Cause string from the AMD engine (e.g. HUMAN, INITIALSILENCE-2500-2500). Numbers inside AmdCause are detector thresholds in milliseconds, not the detection duration. Empty string when not provided. |
MachineDetectionDuration | String | AMD detection duration in integer seconds as a string (e.g. 4). 0 when AMD completes within the same second. Empty string when not provided. |
CallStatus | String | Call state at the time AMD completed (e.g. in-progress, completed). This field reflects the state at time of result; it does not change the call. |
Content-Type defaults to multipart/form-data. Pass StatusCallbackContentType=application/json on the original request to receive JSON instead.
Hanging up after AMD
The platform does not auto-hangup. Use the Call Details API to find the leg SID, then call the hangup action:
# 1. Get the active leg SID
GET /v1/Accounts/{account_sid}/Calls/{call_sid}/ActiveLegs
# 2. Hang up that leg
PUT /v1/Accounts/{account_sid}/Calls/{call_sid}/Legs/{leg_sid}
Action=hangup
Code Examples
- cURL
- Python
- Node.js
- PHP
- Go
curl -u '<api_key>:<api_token>' -X POST 'https://api.exotel.com/v1/Accounts/<your_sid>/Calls/connect' \
-d 'From=+91XXXXXXXXXX' \
-d 'To=+91XXXXXXXXXX' \
-d 'CallerId=XXXXXXXXXX' \
-d 'Record=true' \
-d 'StatusCallback=https://yoururl.com/callback'
import requests
data = {
'From': '+919876543210',
'To': '+919123456789',
'CallerId': '0XXXXXX4890',
'Record': 'true'
}
response = requests.post(
'https://api.exotel.com/v1/Accounts/<your_sid>/Calls/connect',
auth=('<api_key>', '<api_token>'),
data=data
)
print(response.json())
const apiKey = '<your_api_key>';
const apiToken = '<your_api_token>';
const accountSid = '<your_sid>';
const url = `https://api.exotel.com/v1/Accounts/${accountSid}/Calls/connect`;
const params = new URLSearchParams({
From: '+919876543210',
To: '+919123456789',
CallerId: '0XXXXXX4890',
Record: 'true',
});
const response = await fetch(url, {
method: 'POST',
headers: {
'Authorization': 'Basic ' + Buffer.from(`${apiKey}:${apiToken}`).toString('base64'),
'Content-Type': 'application/x-www-form-urlencoded',
},
body: params,
});
const data = await response.json();
console.log(data);
<?php
$data = array(
'From' => '+919876543210',
'To' => '+919123456789',
'CallerId' => '0XXXXXX4890',
'Record' => 'true'
);
$ch = curl_init('https://api.exotel.com/v1/Accounts/<your_sid>/Calls/connect');
curl_setopt($ch, CURLOPT_USERPWD, "<api_key>:<api_token>");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
package main
import (
"fmt"
"io/ioutil"
"net/http"
"net/url"
"strings"
)
func main() {
endpoint := "https://api.exotel.com/v1/Accounts/<your_sid>/Calls/connect"
data := url.Values{}
data.Set("From", "+919876543210")
data.Set("To", "+919123456789")
data.Set("CallerId", "0XXXXXX4890")
data.Set("Record", "true")
req, _ := http.NewRequest("POST", endpoint, strings.NewReader(data.Encode()))
req.SetBasicAuth("<api_key>", "<api_token>")
req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(string(body))
}
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
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
Sid | String | Unique alpha-numeric call identifier |
DateCreated | DateTime | When the API request was initiated |
DateUpdated | DateTime | Last status update timestamp |
AccountSid | String | Your Exotel Account SID |
To | String | The destination phone number |
From | String | The number called first |
PhoneNumberSid | String | The ExoPhone used |
Status | String | queued, in-progress, completed, failed, busy, no-answer |
StartTime | DateTime | When call was sent to operator |
EndTime | DateTime | When call ended |
Duration | Integer | Total duration in seconds |
Price | Double | Amount charged (INR/USD) |
Direction | String | inbound, outbound-dial, outbound-api |
RecordingUrl | String | Recording URL (if enabled) |
Call Status Values
| Status | Description |
|---|---|
queued | Waiting to be sent to operator |
in-progress | Call is active |
completed | Ended normally |
failed | Could not be completed |
busy | Busy signal received |
no-answer | Not answered within timeout |
Duration, Price, and EndTime update asynchronously (~2 minutes after call ends). Use StatusCallback or Call Details API for final values.
Audio file URLs for WaitUrl are cached. Use unique URLs (e.g., add a query parameter) when updating audio files.
Error Responses
When a request fails, the API returns an error JSON:
400 — Missing required parameter:
{
"RestException": {
"Status": 400,
"Message": "The 'From' parameter is required."
}
}
401 — Authentication failed:
{
"RestException": {
"Status": 401,
"Message": "Authentication failed. Verify your API key and token."
}
}
429 — Rate limit exceeded:
{
"RestException": {
"Status": 429,
"Message": "Rate limit exceeded. Max 200 requests per minute."
}
}
For a complete list of error codes, see the Error Code Dictionary.