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:
You must POST the following parameters:
|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).
SIP addresses must be formatted as
email@example.com. For example, to dial Alice's SIP address at Example Company, the
To parameter should be
Client identifiers must begin with the
client: URI scheme. For example, to call a client named 'jenny', the
To parameter should be
You must also POST one of the following parameters:
|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:
|Method||The HTTP method Twilio should use when making its request to the above |
|FallbackUrl||A URL that Twilio will request if an error occurs requesting or executing the TwiML at |
|FallbackMethod||The HTTP method that Twilio should use to request the |
|StatusCallback||A URL that Twilio will send asynchronous webhook requests to on every call event specified in the |
|StatusCallbackMethod||The HTTP method Twilio should use when requesting the above URL. Defaults to |
|StatusCallbackEvent||The call progress events that Twilio will send webhooks on. Available values are |
|SendDigits||A string of keys to dial after connecting to the number, maximum of 32 digits. Valid digits in the string include: any digit (|
|IfMachine||Tell Twilio to try and determine if a machine (like voicemail) or a human has answered the call. Possible values are |
|Timeout||The integer number of seconds that Twilio should allow the phone to ring before assuming there is no answer. Default is |
|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:
|AnsweredBy||A string describing what answered the call. Either |
For every call progress event specified in the
Twilio will make an asynchronous webhook to the
StatusCallback if you
provided one in your
The parameters Twilio passes to your application in its asynchronous request to
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
When the call progress events are fired, the Status Callback request also passes these additional parameters:
|CallStatus||A descriptive status for the call. The value is one of |
|CallDuration||The duration in seconds of the just-completed call. Only present in the |
|RecordingUrl||The URL of the phone call's recorded audio. This parameter is included only if |
|RecordingSid||The unique ID of the Recording from this call. |
|RecordingDuration||The duration of the recorded audio (in seconds). |
|Timestamp||The timestamp when the event was fired, given as UTC in RFC 2822 format.|
|CallbackSource||A 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 |
|SequenceNumber||The order in which the events were fired, starting from |
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.
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
StatusCallbackEvent is specified the
completed event will be sent by
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.
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. Twilio will POST to
http://demo.twilio.com/docs/voice.xml to fetch TwiML to handle the call.
Make a call from 415-867-5309 to a Twilio Client named
Twilio will POST to
http://demo.twilio.com/docs/voice.xml to fetch TwiML to
handle the call.
Make a call from 866-867-5309 to 415-555-1212 after dialing extension 1234#.
Twilio will send a GET request to
fetch TwiML to handle the call.
Make a call from 866-867-5309 to 415-555-1212, and
POST all the call progress events to
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
Keep in mind that if a machine answers you'll want to avoid using
<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.