Prefer a step-by-step guide to making your first call? Check out our Programmable Voice quickstart in C#, Java, Node.js, PHP, Python, Ruby, or Go.
Initiate an outbound call with Twilio
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:
_10
/2010-04-01/Accounts/{AccountSid}/Calls
(warning)
Warning
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 From and To for Twilio to know where to direct the outbound call and what to use as the caller ID.
Specify the call's recipient
The 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).
(warning)
Warning
If you are making calls from a trial account, the To phone number must be verified with Twilio. You can verify your phone number by adding it to your Verified Caller IDs in the console.
SIP addresses must be formatted as sip:name@example.com. For example, to dial Pat's SIP address at Example Company, the To parameter should be sip:pat@example.com.
Client identifiers must begin with theclient:URI scheme. For example, to call a client named joey, the To parameter should be client:joey.
Specify the caller ID
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).
Any phone number you specify here must be a Twilio phone number (you can purchase a number through the console) or a verified outgoing caller id for your account.
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 client:charlie.
Tell Twilio what to do on the call
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
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.
(warning)
Warning
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 Voice SDK device, 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.
Make an outbound call to a phone number
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
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.
(warning)
Warning
Using an ApplicationSid in your request will cause Twilio to ignore the following parameters, even if you include them in your POST: Url, Method, FallbackUrl, FallbackMethod, StatusCallback, and 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.
Manage your outbound call
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 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.
Make a call and send digits
This code will make a call and then dial extension 1234# after the call is connected.
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
// Find your Account SID and Auth Token at twilio.com/console
_16
// and set the environment variables. See http://twil.io/secure
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?
Monitor outbound call events
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.
Call end: setting your StatusCallback
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.
(warning)
Warning
Any 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.
Set StatusCallback on an outbound call
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_17
// Download the helper library from https://www.twilio.com/docs/node/install
_17
// Find your Account SID and Auth Token at twilio.com/console
_17
// and set the environment variables. See http://twil.io/secure
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.
The optional 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, ringing, answered, or completed: