Simple Example for Placing Programmable Voice Calls – Twilio Support

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 To parameter consisting of the desired destination phone number (using E.164 formatting) for receiving this call.
Caller: The From parameter 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 -
- The Url parameter consisting of a web address that responds to our requests with TwiML.
- The ApplicationSid parameter 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/" \
-u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

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).

TwiML Instructions

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:

a <Dial> verb to connect the destination callee to a Twilio Conference, Client instance, SIP endpoint, or another phone number.
a <Gather> verb to collect speech of DTMF keypress inputs from the destination callee.
a <Say> or <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.

Additional Resources