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:

ParameterDescription
FromThe 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.
ToThe 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:

ParameterDescription
UrlThe 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.
ApplicationSidThe 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:

ParameterDescription
MethodThe 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.
FallbackUrlA 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.
FallbackMethodThe 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.
StatusCallbackA URL that Twilio will send asynchronous webhook requests to on every call event specified in the StatusCallbackEvent parameter. If no event is present, Twilio will send completed by default. If an ApplicationSid parameter is present, this parameter is ignored.
StatusCallbackMethodThe HTTP method Twilio should use when requesting the above URL. Defaults to POST. If an ApplicationSid parameter is present, this parameter is ignored.
StatusCallbackEventThe call progress events that Twilio will send webhooks on. Available values are initiated, ringing, answered, and completed. If you want to receive multiple events, pease provide multiple StatusCallbackEvent values as individual parameters in the POST request. See Example 4. If no event is specified, defaults to completed. If an ApplicationSid is present, this parameter is ignored.
SendDigitsA 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.
IfMachineTell 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.
TimeoutThe 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.
RecordSet 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:

ParameterDescription
AnsweredByA string describing what answered the call. Either human or machine.

StatusCallback Parameter

For every call progress event specified in the StatusCallbackEvent parameter, Twilio will make an asynchronous webhook to the StatusCallback if you provided one in your POST request.

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 request documentation.

When the call progress events are fired, the Status Callback request also passes these additional parameters:

ParameterDescription
CallStatusA descriptive status for the call. The value is one of queued, initiated, ringing, in-progress, busy, failed, or no-answer. See the CallStatus section for more details.
CallDurationThe duration in seconds of the just-completed call. Only present in the completed event.
RecordingUrlThe 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>. RecordingUrl is only present in the completed event.
RecordingSidThe unique ID of the Recording from this call. RecordingSid is only present in the completed event.
RecordingDurationThe duration of the recorded audio (in seconds). RecordingDuration is only present in the completed event.
TimestampThe timestamp when the event was fired, given as UTC in RFC 2822 format.
CallbackSourceA string that describes the source of the webhook. This is provided to help disambiguate why the webhook was made. On Status Callbacks, this value is always call-progress-events.
SequenceNumberThe order in which the events were fired, starting from 0. Although events are fired in order, they are made as separate HTTP requests and there is no guarantee they will arrive in the same order.

StatusCallbackEvent Parameter

When making a POST request to the Calls resource, an outbound call instance is created and the call starts in the queued status. The initiated event is fired when the call moves to the initiated status and dialing begins. The ringing event is fired when the recipient phone begins ringing. When the recipient picks up, the answered event is fired and the call is now in the in-progress status. The final completed event is fired when the call ends.

The StatusCallbackEvent parameter allows you to specify which events Twilio should webhook on. You can specify multiple events by providing multiple StatusCallbackEvent values (See Example 4). If a StatusCallback is provided and no StatusCallbackEvent is specified the completed event will be sent by default.

The initiated, ringing, and answered events have a cost of $0.0001 per event, which results in $10 for every 100,000 events. The completed event is not charged. The following shows a timeline of possible call events that can be returned and the different call statuses that an outbound API call may experience.

Status Callback Event flow diagram

EventDescriptionCost
initiatedThe initiated event is fired when Twilio starts dialing the call.$0.0001 per event
ringingThe ringing event is fired when the call starts ringing.$0.0001 per event
answeredThe answered event is fired when the call is answered.$0.0001 per event
completedThe completed event is fired when the call is completed, regardless of the termination status: busy, canceled, completed, failed, or no-answer. If no StatusCallbackEvent is specified, completed will be fired by default.No cost

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

Example 4

Make a call from 866-867-5309 to 415-555-1212, and POST all the call progress events to https://www.myapp.com/events.

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.