Get Started

REST API: Making Calls

Using the Twilio REST API, you can make outgoing calls to phones, SIP-enabled endpoints and Twilio Client connections.

Note that calls initiated via the REST API are rate-limited to one per second. You can queue up as many calls as you like as fast as you like, but each call is popped off the queue at a rate of one per second.

HTTP POST to Calls

To make a call, make an HTTP POST request to your account's Calls list resource URI:

/2010-04-01/Accounts/{AccountSid}/Calls

POST Parameters

Required Parameters

You must POST the following parameters:

Parameter Description
From The phone number or client identifier to use as the caller id. If using a phone number, it must be a Twilio number or a Verified outgoing caller id for your account.
To The phone number, SIP address or client identifier to call.

Phone numbers should be formatted with a '+' and country code e.g., +16175551212 (E.164 format). Twilio will also accept unformatted US numbers e.g., (415) 555-1212 or 415-555-1212.

If you are making calls from a trial account, the 'To' phone number must be verified with Twilio.

SIP addresses must be formatted as name@example.com. For example, to dial Alice's SIP address at Example Company, the To parameter should be alice@example.com.

Client identifiers must begin with the client: URI scheme. For example, to call a client named 'jenny', the To parameter should be client:jenny.

You must also POST one of the following parameters:

Parameter Description
Url The fully qualified URL that should be consulted when the call connects. Just like when you set a URL on a phone number for handling inbound calls. See the Url Parameter section below for more details.
ApplicationSid The 34 character sid of the application Twilio should use to handle this phone call. If this parameter is present, Twilio will ignore all of the voice URLs passed and use the URLs set on the application. See the ApplicationSid Parameter section below for more details.
Optional Parameters

You may POST the following parameters:

Parameter Description
Method The HTTP method Twilio should use when making its request to the above Url parameter's value. Defaults to POST. If an ApplicationSid parameter is present, this parameter is ignored.
FallbackUrl A URL that Twilio will request if an error occurs requesting or executing the TwiML at Url. If an ApplicationSid parameter is present, this parameter is ignored.
FallbackMethod The HTTP method that Twilio should use to request the FallbackUrl. Must be either GET or POST. Defaults to POST. If an ApplicationSid parameter is present, this parameter is ignored.
StatusCallback A URL that Twilio will request when the call ends to notify your app. If an ApplicationSid parameter is present, this parameter is ignored.
StatusCallbackMethod The HTTP method Twilio should use when requesting the above URL. Defaults to POST. If an ApplicationSid parameter is present, this parameter is ignored.
SendDigits A string of keys to dial after connecting to the number. Valid digits in the string include: any digit (0-9), '#', '*' and 'w' (to insert a half second pause). For example, if you connected to a company phone number, and wanted to pause for one second, dial extension 1234 and then the pound key, use SendDigits=ww1234#. Remember to URL-encode this string, since the '#' character has special meaning in a URL.
IfMachine Tell Twilio to try and determine if a machine (like voicemail) or a human has answered the call. Possible values are Continue and Hangup. See the answering machines section below for more info.
Timeout The integer number of seconds that Twilio should allow the phone to ring before assuming there is no answer. Default is 60 seconds, the maximum is 999 seconds. Note, you could set this to a low value, such as 15, to hangup before reaching an answering machine or voicemail. Also see the answering machine section for other solutions.
Record Set this parameter to 'true' to record the entirety of a phone call. The RecordingUrl will be sent to the StatusCallback URL. Defaults to 'false'.

Url Parameter

When you initiate a call through the REST API, Twilio makes a synchronous HTTP request to the URL found in the value of the 'Url' POST parameter, in order to retrieve TwiML for handling the call. This request is identical to the request Twilio sends when receiving a phone call to one of your Twilio numbers.

Request Parameters

The parameters Twilio passes to your application in its request include all parameters passed in a synchronous request to retrieve TwiML when Twilio receives a call to one of your Twilio numbers. The full list of those parameters and descriptions of each are in the TwiML Voice: Twilio's Request documentation. There is an additional parameter sent if you use the IfMachine parameter in your request:

Parameter Description
AnsweredBy A string describing what answered the call. Either human or machine.

StatusCallback Parameter

After a call ends, Twilio will make an asynchronous HTTP request to the StatusCallback URL if you provided one in your POST. This will happen regardless of the call status.

Request Parameters

The parameters Twilio passes to your application in its asynchronous request to the StatusCallback URL include all parameters passed in a synchronous request to retrieve TwiML when Twilio receives a call to one of your Twilio numbers. The full list of parameters and descriptions of each are in the TwiML Voice: Twilio's Request documentation.

The Status Callback request also passes these additional parameters:

Parameter Description
CallDuration The duration in seconds of the just-completed call.
RecordingUrl The URL of the phone call's recorded audio. This parameter is included only if Record=true is set on the REST API request, and does not include recordings from <Dial> or <Record>.
RecordingSid The unique id of the Recording from this call.
RecordingDuration The duration of the recorded audio (in seconds).

ApplicationSid Parameter

Within Twilio, an application is a set of URLs and other configuration data for handling voice calls and SMS. You can create and configure applications in the Apps section of the account portal. Since an application contains all of the information required to handle a phone call, it makes sense to use applications to handle outbound calls.

If you POST an 'ApplicationSid' parameter, Twilio will use all of the URLs and other configuration information from that application to handle the outbound call, and will ignore all of the following parameters in your POST: 'Url', 'Method', 'FallbackUrl', 'FallbackMethod', 'StatusCallback', and 'StatusCallbackMethod'.

When the outbound call is connected, Twilio will make a request to the 'VoiceUrl' set on the application. This request is identical to the request Twilio would have sent to the 'Url' parameter as detailed above.

After a call ends, Twilio will make an asynchronous HTTP request to the StatusCallback URL set on the application. This request is identical to the request Twilio would have sent to the 'StatusCallback' parameter as detailed above.

Examples

Example 1

Make a call from 415-867-5309 to 415-555-1212, POSTing to http://www.myapp.com/myhandler.php

Example 2

Make a call from 415-867-5309 to a Twilio Client named tommy. Twilio will POST to http://www.myapp.com/myhandler.php to fetch TwiML to handle the call.

Example 3

Make a call from 866-867-5309 to 415-555-1212, after connecting dialing extension 1234#, and GETing http://www.myapp.com/myhandler.php

Handling Possible Call Outcomes

When Twilio makes its synchronous request to the URL given in the Url parameter of your POST, it behaves exactly as it does when requesting TwiML from your application in response to receiving an incoming call. The parameters passed in this request are the usual TwiML Voice request parameters.

Answering Machines

IMPORTANT: Answering machine detection is an experimental feature, and support is limited. The downside of trying to detect a machine is that Twilio needs to listen to the first few seconds of audio after connecting a call. This usually results in a few seconds of delay before Twilio begins processing TwiML. If your application does not care about the human vs. machine distinction, then omit the 'IfMachine' parameter and Twilio will perform no such analysis.

Twilio can try to detect if an answering machine has answered a call, and can handle the call differently if it is indeed a machine. By default, Twilio does not attempt to determine if a machine or a human has answered the call. Twilio just commences with the call flow.

If you turn on answering machine detection using the 'IfMachine' parameter, Twilio will inform you in its TwiML request whether or not it thinks an answering machine has answered. In this case the 'AnsweredBy' parameter is set to either 'human' or 'machine'.

The Default Behavior

By default if you don't POST an 'IfMachine' parameter, Twilio does not try to detect whether the answering party is a machine (or voicemail) or a human. If anybody or anything picks up the call, Twilio will begin executing the call flow immediately. Note, if you're expecting to "leave a message" on an answering machine, the call flow will likely begin before the "beep" is reached, and therefore the machine likely won't capture the beginning of your call content. To handle this use 'IfMachine=Continue' as documented below.

Hanging Up

If a machine answers and your application does not want to talk to answering machines, then you can specify 'IfMachine=Hangup' in your POST to start the call. If Twilio detects that a machine, not a human, has answered the call, Twilio will immediately hangup.

If Twilio detects a human has answered the call, then Twilio will make a request to your application URL with the 'AnsweredBy' parameter set to 'human' and the call flow will proceed as normal.

Continuing If A Machine Answers

If your application would like to know if a human or a machine answered, and will perhaps return different content based on the situation, then you can specify 'IfMachine=Continue' in your POST to start the call.

If Twilio detects that a machine, not a human, has answered the call, Twilio will make a request to your application URL setting 'AnsweredBy' to 'machine'. The call flow will proceed as normal, and your application can choose to customize the content of the call for a recorded greeting. Twilio will wait until the familiar "BEEP" of an answering machine to begin executing your call flow, so the machine (or voicemail) will capture <Play> or <Say> content. Keep in mind that if a machine answers you'll want to avoid using <Gather> or <Record> because they require user input.

If Twilio detects that a human has answered the call, Twilio will make a request to your application URL setting 'AnsweredBy' to 'human' and call flow will proceed as normal.