Looking for the API Reference docs? Check out the full API reference for Calls.
In this guide, we'll explore how you can use Twilio's Programmable Voice API to:
To place an outbound call, a phone call from a Twilio phone number to an outside number, you must make an HTTP POST request to your account's Call resource:
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 want, but each call is popped off the queue at a rate of one per second.
Your POST request to the API must include the parameters
To for Twilio to know where to direct the outbound call and what to use as the caller ID.
To parameter (required) is the phone number, SIP address, or client identifier you’re calling.
Phone numbers should be formatted with a '+' and country code e.g.,
+16175551212 (E.164 format).
SIP addresses must be formatted as
sip:firstname.lastname@example.org. For example, to dial
Pat'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
To parameter should be
Twilio uses the
From parameter (required) to set a phone number or client identifier as the caller ID for your outbound call.
If you used a phone number for your
To value in your POST request, the
From value you specify must also be a phone number. Just as with the
To parameter, phone numbers should be formatted with a '+' and country code, e.g., +16175551212 (E.164 format).
If you use a client identifier as the value for
From, your identifier must begin with the
client:URI scheme. For example, to set a client named
charlie as your caller ID, your
From parameter should be
When you initiate an outbound call with the Twilio REST API, Twilio needs to access your instructions for how to handle the call. It does this by making a synchronous HTTP request to either:
- a URL that hosts a set of TwiML instructions (this could be an XML document or web application) or
- the set of URLs and configuration you've created as an application in the Twilio console
If you specify a URL parameter in your request, Twilio will make its HTTP request to this URL to retrieve TwiML to handle the call. This request from Twilio is identical to the request Twilio sends when receiving an inbound call.
URLs must contain a valid hostname, and underscores are not permitted.
The following examples show how to create an outbound call to a phone number, a Twilio Client endpoint, and a SIP address with the REST API.
In all three examples, Twilio will POST to
http://demo.twilio.com/docs/voice.xml to fetch TwiML for handling the call.
If you instead specify an
ApplicationSid parameter in your POST request, Twilio will use all of the URLs and other configuration information from that application to handle the outbound call.
Using an ApplicationSid in your request will cause Twilio to ignore the following parameters, even if you include them in your POST:
StatusCallbackMethod. Twilio expects that your application code will handle all of this information.
You can create and configure applications in the TwiML Apps section of the console. Since an application contains all of the information required to handle a phone call, it makes sense to use applications to handle outbound calls with complicated call flows.
When your outbound call is connected, Twilio will make a request to the VoiceUrl set on your application. This request is identical to the request Twilio would have sent to the Url parameter, as detailed above.
When POSTing to the REST API's Calls list endpoint, you may wish to tell Twilio to take specific actions on your outbound call by sending additional parameters in your request. These could include (but are not limited to) waiting a certain amount of time for an answer, dialing an extension, or recording a call.
For the full list of parameters you can pass in your POST request, check out the detailed API reference documentation for creating a Call resource.
For example, if you wish to make an outbound call and send digits in order to dial an extension, you would add the optional
SendDigits parameter to your request.
To tell Twilio to record an outbound call, include the optional parameter
Record and set its value to
With this code, Twilio will connect the outbound call and make a recording of it. But how do you get your hands on that recording and other information about the call?
In the code above, we set
Record=true, but we didn't give Twilio any instructions on what to do with that recording, or any other information about the call, once the call ends. Here's where the
StatusCallback parameter comes into play.
After an outbound call ends, Twilio will make an asynchronous HTTP request to the
StatusCallback URL specified in your POST request. If you don't provide a URL for this parameter, Twilio will simply end the call without sending information back to you.
StatusCallback URL you set must contain a valid hostname. Underscores are not permitted.
Let's update the POST request to place an outbound call, specifying a
StatusCallback URL this time to tell Twilio where to send data after the call ends.
Note that you can specify a
StatusCallbackMethod to tell Twilio what kind of HTTP request to make to your
StatusCallback URL. This is an optional parameter that defaults to POST.
When the call shown above ends, Twilio will send all of the same parameters it uses when someone places a call to one of your Twilio phone numbers. Check out the full list of parameters Twilio always sends with this request.
StatusCallbackEvent parameter lets you specify which call progress events Twilio will act on. You can use this parameter to tell Twilio to send information to the
StatusCallback URL you specified when a call is
initiated event is fired when Twilio removes your call from the queue and starts dialing the call
ringing event is fired when the call starts ringing
answered event fires when someone answers the call
completed event is fired when the call ends, regardless of the termination status:
no-answer. This means that when the call has finished execution, one of those termination statuses will be returned. If no
StatusCallbackEvent is specified,
completed will fire by default.
With the following code, Twilio will POST information about the outbound call when the call dequeues and starts dialing.
If you leave the
StatusCallbackEvent out of your request but still specify a
StatusCallback URL, Twilio will default to the event to
completed and send data to your URL after the call ends.
If you request a recording of an outbound call by specifying
Record=true, you can set a
RecordingStatusCallback URL so that Twilio will make a GET or POST request to your URL when the recording is available.
Twilio will send information to your specified
RecordingStatusCallback URL like the
RecordingStatus, and the
RecordingUrl (the URL where you can access the recording).
Check out the full list of parameters that Twilio will pass with its request to your
To pause, resume, or stop recordings programmatically, see the Recording API Docs. Or, explore our guides for recording phone calls using Twilio's helper libraries.
Just as an outbound call has a series of status events, so does the recording Twilio makes for you.
By setting the
RecordingStatusCallbackEvent, you can specify which recording status changes should trigger a request to your
RecordingStatusCallback URL. The
RecordingStatusCallbackEvent values default to
completed, but possible values are
in-progress. To specify more than one value, separate each with a space.
After Twilio completes your outbound call, it will make a synchronous request to the URL you specified in your POST request. In this request, Twilio sends all of its standard request parameters.
From here, it’s up to you what happens next! You may wish to trigger another event, like send an SMS to the
To phone number you just called with a follow-up message, or try to place the call again if the CallStatus returns
You can also explore all of our Programmable Voice tutorials to learn how to modify calls in progress programmatically, record phone calls, create conference calls, and more.