Skip to main content

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​

ParameterRequiredTypeDescription
FromYesStringThe number called first. Accepts an E.164 phone number (e.g., +919900XXXXXX) or a SIP URI (e.g., sip:agent@exotel.com).
ToYesStringCustomer phone number. E.164 format only (e.g., +918800XXXXXX).
CallerIdYesStringYour ExoPhone/virtual number.
CallTypeNoStringtrans for transactional calls.
TimeLimitNoIntegerMax call duration in seconds. Max: 14400 (4 hours).
TimeOutNoIntegerTime 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.
WaitUrlNoStringAudio URL (WAV) played while waiting. Recommended: under 2MB.
RecordNoBooleantrue to record the conversation.
RecordingChannelsNoStringsingle (default) or dual.
RecordingFormatNoStringmp3 (default) or mp3-hq.
StreamUrlNoStringWebSocket URL for real-time audio streaming.
StreamBeginNoStringat Leg1Connect or at Leg2Connect.
CustomFieldNoStringMetadata (max 128 chars). Passed to StatusCallback and applets.
StartPlaybackToNewNoStringCallee (default) or Both.
StartPlaybackValueNewNoStringAudio URL for pre-call playback.
StatusCallbackNoStringWebhook URL for call status updates.
StatusCallbackEventsNoArrayterminal, answered, or both.
StatusCallbackContentTypeNoStringmultipart/form-data (default) or application/json. Applies to both StatusCallback and AsyncAmdStatusCallback.
MachineDetectionNoStringEnable answering machine detection: Enable or Disable (default). Case-insensitive. Omitting the parameter is treated as Disable. Empty string is invalid and returns 400.
AsyncAmdNoStringRequired when MachineDetection=Enable. Must be true. Any other value returns 400. Synchronous AMD is not supported.
AsyncAmdStatusCallbackNoStringRequired 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

ConditionResult
MachineDetection omittedTreated as Disable; AMD params ignored
MachineDetection=DisableAMD params present but ignored; no 400
MachineDetection=Enable, valid AsyncAmd=true and AsyncAmdStatusCallbackAMD enabled
MachineDetection=Enable, missing or invalid AsyncAmd or AsyncAmdStatusCallback400
MachineDetection= (empty string)400

AsyncAmdStatusCallback payload

Exotel POSTs to your URL when AMD completes. This fires even if the call has already ended.

FieldTypeDescription
CallSidStringCall SID
AccountSidStringAccount SID
AnsweredByStringHUMAN, MACHINE, or NOTSURE
AmdCauseStringCause 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.
MachineDetectionDurationStringAMD detection duration in integer seconds as a string (e.g. 4). 0 when AMD completes within the same second. Empty string when not provided.
CallStatusStringCall 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 -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'

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​

FieldTypeDescription
SidStringUnique alpha-numeric call identifier
DateCreatedDateTimeWhen the API request was initiated
DateUpdatedDateTimeLast status update timestamp
AccountSidStringYour Exotel Account SID
ToStringThe destination phone number
FromStringThe number called first
PhoneNumberSidStringThe ExoPhone used
StatusStringqueued, in-progress, completed, failed, busy, no-answer
StartTimeDateTimeWhen call was sent to operator
EndTimeDateTimeWhen call ended
DurationIntegerTotal duration in seconds
PriceDoubleAmount charged (INR/USD)
DirectionStringinbound, outbound-dial, outbound-api
RecordingUrlStringRecording URL (if enabled)

Call Status Values​

StatusDescription
queuedWaiting to be sent to operator
in-progressCall is active
completedEnded normally
failedCould not be completed
busyBusy signal received
no-answerNot answered within timeout
note

Duration, Price, and EndTime update asynchronously (~2 minutes after call ends). Use StatusCallback or Call Details API for final values.

info

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.

Try It​