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.
To make a call, make an HTTP POST request to your account's Calls list resource URI:
/2010-04-01/Accounts/{AccountSid}/Calls
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.
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. |
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'. |
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.
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. |
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.
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). |
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.
Make a call from 415-867-5309 to 415-555-1212, POSTing to http://www.myapp.com/myhandler.php
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.
Make a call from 866-867-5309 to 415-555-1212, after connecting dialing extension 1234#, and GETing http://www.myapp.com/myhandler.php
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.
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'.
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.
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.
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.