To place a call, your application needs to make an HTTP POST request to Twilio’s Calls API resource with three required pieces of information; A recipient, a caller, and some TwiML Instructions for running your call.
- Recipient: The
Toparameter consisting of the desired destination phone number (using E.164 formatting) for receiving this call.
- Caller: The
Fromparameter consisting of a valid Twilio phone number, or a verified Caller ID (using E.164 formatting).
- TwiML Instructions: One of the following to tell us where to request TwiML instructions -
Urlparameter consisting of a web address that responds to our requests with TwiML.
ApplicationSidparameter consisting of a TwiML App SID containing a web address that responds to our requests with TwiML.
Here’s an example cURL script:
curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls.json \ --data-urlencode "To=+13105555555" \ --data-urlencode "From=+12125551234" \
--data-urlencode "Url=https://demo.twilio.com/welcome/voice/" \
This example will place an outbound call from the sender (212) 555-1234 (
+12125551234) to the phone number (310) 555-5555 (
+13105555555), and then execute the TwiML script at https://demo.twilio.com/welcome/voice/. To make this script work for you, make the following updates, and then paste it into a terminal window:
- Line 1 update with your Account SID
- Line 2 update with a valid destination
- Line 3 update with a valid caller number
- Line 4 update with a valid TwiML URL or App SID url
- Line 5 update with your Account SID and Auth Token
Additional optional parameters can be added in your request for recording the call, sending DTMF keypresses, requesting status change updates, and more. For full details on each of the available options, please see Call Parameters (Twilio Docs).
Once the call is connected, Twilio will make an HTTP Request to the Url or ApplicationSid included in your initial API request. Twilio's request contains a number of parameters, including the To and From numbers, the Call SID to identify your call, and more.
In response to our request, we expect TwiML commands to tell us how to run the call. Here are some examples:
<Dial>verb to connect the destination callee to a Twilio Conference, Client instance, SIP endpoint, or another phone number.
<Gather>verb to collect speech of DTMF keypress inputs from the destination callee.
<Play>verb to read a script with our text-to-speech engine or play a pre-recorded audio file for the destination callee.
TwiML responses can be formatted in XML and nested in the root
<Response> element, or they can be returned programmatically using one of our Server-side SDKs. For more information on the voice TwiML commands, their parameters, and code samples, please see What is TwiML (Twilio Docs).
Notice: TwiML instructions must be accessible by Twilio's proxy servers. Local files on your desktop are likely unaccessible via these methods, but Twiilio can host XML-formatted TwiML responses via TwiML Bins, or Node.js responses via Twilio Functions.
Another convenient tool for sending messages is the API Explorer in Console. From here, you can place a call using easy to update fields and drop-down menus. You can even see the code change in real-time as your adjust the parameters. Click here to try it yourself: API Explorer - Make a Call.