REST API: Making Calls

Using the Twilio REST API, you can make outgoing calls to phones, SIP-enabled endpoints and Twilio Client connections.

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.

HTTP POST to Calls

To make a call, make an HTTP POST request to your account's Calls list resource URI:

/2010-04-01/Accounts/{AccountSid}/Calls

POST Parameters

Required Parameters

You must POST the following parameters:

Parameter Description
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][e164] format).

If you are making calls from a trial account, the 'To' phone number must be verified with Twilio.

SIP addresses must be formatted as name@example.com. For example, to dial Alice's SIP address at Example Company, the To parameter should be alice@example.com.

Client identifiers must begin with the client: URI scheme. For example, to call a client named 'jenny', the To parameter should be client:jenny.

You must also POST one of the following parameters:

Parameter Description
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.
Optional Parameters

You may POST the following parameters:

Parameter Description
Method The HTTP method Twilio should use when making its request to the above Url parameter's value. Defaults to POST. If an ApplicationSid parameter is present, this parameter is ignored.
FallbackUrl A URL that Twilio will request if an error occurs requesting or executing the TwiML at Url. If an ApplicationSid parameter is present, this parameter is ignored.
FallbackMethod The HTTP method that Twilio should use to request the FallbackUrl. Must be either GET or POST. Defaults to POST. If an ApplicationSid parameter is present, this parameter is ignored.
StatusCallback A URL that Twilio will send asynchronous webhook requests to on every call event specified in the StatusCallbackEvent parameter. If no event is present, Twilio will send completed by default. If an ApplicationSid parameter is present, this parameter is ignored.
StatusCallbackMethod The HTTP method Twilio should use when requesting the above URL. Defaults to POST. If an ApplicationSid parameter is present, this parameter is ignored.
StatusCallbackEvent The call progress events that Twilio will send webhooks on. Available values are initiated, ringing, answered, and completed. If you want to receive multiple events, please provide multiple StatusCallbackEvent values as individual parameters in the POST request. See Example 4. If no event is specified, defaults to completed. If an ApplicationSid is present, this parameter is ignored.
SendDigits A string of keys to dial after connecting to the number, maximum of 32 digits. Valid digits in the string include: any digit (0-9), '#', '*' and 'w' (to insert a half second pause). For example, if you connected to a company phone number, and wanted to pause for one second, dial extension 1234 and then the pound key, use SendDigits=ww1234#. Remember to URL-encode this string, since the '#' character has special meaning in a URL. If both SendDigits and IfMachine parameters are provided, then IfMachine will be ignored.
IfMachine Tell Twilio to try and determine if a machine (like voicemail) or a human has answered the call. Possible values are Continue and Hangup. See the answering machines section below for more info. If both SendDigits and IfMachine parameters are provided, then IfMachine will be ignored.
Timeout The integer number of seconds that Twilio should allow the phone to ring before assuming there is no answer. Default is 60 seconds, the maximum is 999 seconds. Note, you could set this to a low value, such as 15, to hangup before reaching an answering machine or voicemail. Also see the answering machine section for other solutions.
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'.

New:

Parameter Description
RecordingChannels mono or dual

Set this parameter to specify the number of channels in the final .wav recording. Defaults to 'mono'.

For the dual-channel formats, the parent call will always be in the first channel and the child call will always be in the second channel.
RecordingStatusCallback The recordingStatusCallback attribute takes an absolute URL as an argument.
RecordingStatusCallbackMethod The HTTP method Twilio should use when requesting the above URL. Defaults to POST

Url Parameter

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][4] when receiving a phone call to one of your Twilio numbers.

Request Parameters

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:

Parameter Description
AnsweredBy A string describing what answered the call. Either human or machine.

StatusCallback Parameter

For every call progress event specified in the StatusCallbackEvent parameter, Twilio will make an asynchronous webhook to the StatusCallback if you provided one in your POST request.

Request Parameters

The parameters Twilio passes to your application in its asynchronous request to the 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 request documentation][twiml-voice-request].

When the call progress events are fired, the Status Callback request also passes these additional parameters:

Parameter Description
CallStatus A descriptive status for the call. The value is one of queued, initiated, ringing, in-progress, busy, failed, or no-answer. See the [CallStatus section][call-status] for more details.
CallDuration The duration in seconds of the just-completed call. Only present in the completed event.
RecordingUrl The URL of the phone call's recorded audio. This parameter is included only if Record=true is set on the REST API request and does not include recordings from <Dial> or <Record>. RecordingUrl is only present in the completed event.
RecordingSid The unique ID of the [Recording][recordings] from this call. RecordingSid is only present in the completed event.
RecordingDuration The duration of the recorded audio (in seconds). RecordingDuration is only present in the completed event.
Timestamp The timestamp when the event was fired, given as UTC in [RFC 2822][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 call-progress-events.
SequenceNumber The order in which the events were fired, starting from 0. Although events are fired in order, they are made as separate HTTP requests and there is no guarantee they will arrive in the same order.

RecordingStatusCallback Parameter

The RecordingStatusCallback attribute takes a URL as an argument.

If a recording has been requested for the call and a recordingStatusCallback URL is given, Twilio will make a POST request to this URL when the recording is available.

Request Parameters

Twilio will pass the following parameters with its request to the RecordingStatusCallback URL:

Parameter Description
ParentCallSid A unique identifier for the parent call, generated by Twilio.
RecordingSid The unique identifier for the recording.
RecordingStatus The status of the recording. Possible values are: completed.
RecordingUrl The URL of the recorded audio.

StatusCallbackEvent Parameter

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.

The 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 and no StatusCallbackEvent is specified the completed event will be sent by default.

The initiated, ringing, and answered events have a cost of $0.0001 per event, which results in $10 for every 100,000 events. The completed event is not charged. 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.

Status Callback Event flow diagram

Event Description
queued The queued event is fired when Twilio creates the call and adds it to your call queue.
initiated The initiated event is fired when Twilio removes your call from the queue and starts dialing the call.
ringing The ringing event is fired when the call starts ringing.
answered The answered event is fired when the call is answered.
completed The completed event is fired when the call is completed, regardless of the termination status: busy, canceled, completed, failed, or no-answer. If no StatusCallbackEvent is spec

ApplicationSid Parameter

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.

Examples

Example 1

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.

Example 1
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var options = new CallOptions();
    options.Url = "http://demo.twilio.com/docs/voice.xml";
    options.To = "+14155551212";
    options.From = "+14158675309";
    var call = twilio.InitiateOutboundCall(options);
    
    Console.WriteLine(call.Sid);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.CallFactory;
import com.twilio.sdk.resource.instance.Call;
import com.twilio.sdk.resource.list.CallList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the CallList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("Url", "http://demo.twilio.com/docs/voice.xml"));
    params.add(new BasicNameValuePair("To", "+14155551212"));
    params.add(new BasicNameValuePair("From", "+14158675309"));
    
    
    CallFactory callFactory = client.getAccount().getCallFactory();
    Call call = callFactory.create(params);
    System.out.println(call.getSid());
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.calls.create({
    url: "http://demo.twilio.com/docs/voice.xml",
    to: "+14155551212",
    from: "+14158675309"
}, function(err, call) {
    process.stdout.write(call.sid);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "{{ auth_token }}"; 
$client = new Services_Twilio($sid, $token);

$call = $client->account->calls->create("+14158675309", "+14155551212", "http://demo.twilio.com/docs/voice.xml", array());
echo $call->sid;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

call = client.calls.create(url="http://demo.twilio.com/docs/voice.xml",
    to="+14155551212",
    from_="+14158675309")
print call.sid
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token

call = @client.account.calls.create(:url => "http://demo.twilio.com/docs/voice.xml",
    :to => "+14155551212",
    :from => "+14158675309")
puts call.to
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls.json \
    -d "Url=http://demo.twilio.com/docs/voice.xml" \
    -d "To=%2B14155551212" \
    -d "From=%2B14158675309" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls \
    -d "Url=http://demo.twilio.com/docs/voice.xml" \
    -d "To=%2B14155551212" \
    -d "From=%2B14158675309" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
Show Output
  • JSON
  • XML
{
	"sid": "CAa346467ca321c71dbd5e12f627deb854",
	"date_created": "Thu, 19 Aug 2010 00:12:15 +0000",
	"date_updated": "Thu, 19 Aug 2010 00:12:15 +0000",
	"parent_call_sid": null,
	"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"to": "+14155551212",
	"formatted_to": "(415) 555-1212",
	"from": "+14158675309",
	"formatted_from": "(415) 867-5309",
	"phone_number_sid": "PNd6b0e1e84f7b117332aed2fd2e5bbcab",
	"status": "queued",
	"start_time": null,
	"end_time": null,
	"duration": null,
	"price": null,
	"direction": "outbound-api",
	"answered_by": null,
	"api_version": "2010-04-01",
	"forwarded_from": null,
	"caller_name": null,
	"uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAa346467ca321c71dbd5e12f627deb854.json",
	"subresource_uris": {
		"notifications": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAa346467ca321c71dbd5e12f627deb854\/Notifications.json",
		"recordings": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAa346467ca321c71dbd5e12f627deb854\/Recordings.json"
	}
}
<TwilioResponse>
	<Call>
		<Sid>CAa346467ca321c71dbd5e12f627deb854</Sid>
		<DateCreated>Thu, 19 Aug 2010 00:25:48 +0000</DateCreated>
		<DateUpdated>Thu, 19 Aug 2010 00:25:48 +0000</DateUpdated>
		<ParentCallSid/>
		<AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
		<To>+14155551212</To>
		<FormattedTo>(415) 555-1212</FormattedTo>
		<From>+14158675309</From>
		<FormattedFrom>(415) 867-5309</FormattedFrom>
		<PhoneNumberSid></PhoneNumberSid>
		<Status>queued</Status>
		<StartTime/>
		<EndTime/>
		<Duration/>
		<Price/>
		<Direction>outbound-api</Direction>
		<AnsweredBy/>
		<ApiVersion>2010-04-01</ApiVersion>
		<ForwardedFrom/>
		<CallerName/>
		<Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAa346467ca321c71dbd5e12f627deb854</Uri>
		<SubresourceUris>
			<Notifications>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAa346467ca321c71dbd5e12f627deb854/Notifications</Notifications>
			<Recordings>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAa346467ca321c71dbd5e12f627deb854/Recordings</Recordings>
		</SubresourceUris>
	</Call>
</TwilioResponse>
Example 2

Make a call from 415-867-5309 to a Twilio Client named tommy. Twilio will POST to http://demo.twilio.com/docs/voice.xml to fetch TwiML to handle the call.

Example 2
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var options = new CallOptions();
    options.Url = "http://demo.twilio.com/docs/voice.xml";
    options.To = "client:tommy";
    options.From = "+14158675309";
    var call = twilio.InitiateOutboundCall(options);
    
    Console.WriteLine(call.Sid);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.CallFactory;
import com.twilio.sdk.resource.instance.Call;
import com.twilio.sdk.resource.list.CallList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the CallList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("Url", "http://demo.twilio.com/docs/voice.xml"));
    params.add(new BasicNameValuePair("To", "client:tommy"));
    params.add(new BasicNameValuePair("From", "+14158675309"));
    
    
    CallFactory callFactory = client.getAccount().getCallFactory();
    Call call = callFactory.create(params);
    System.out.println(call.getSid());
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.calls.create({
    url: "http://demo.twilio.com/docs/voice.xml",
    to: "client:tommy",
    from: "+14158675309"
}, function(err, call) {
    process.stdout.write(call.sid);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "{{ auth_token }}"; 
$client = new Services_Twilio($sid, $token);

$call = $client->account->calls->create("+14158675309", "client:tommy", "http://demo.twilio.com/docs/voice.xml", array());
echo $call->sid;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

call = client.calls.create(url="http://demo.twilio.com/docs/voice.xml",
    to="client:tommy",
    from_="+14158675309")
print call.sid
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token

call = @client.account.calls.create(:url => "http://demo.twilio.com/docs/voice.xml",
    :to => "client:tommy",
    :from => "+14158675309")
puts call.start_time
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls.json \
    -d "Url=http://demo.twilio.com/docs/voice.xml" \
    -d "To=client:tommy" \
    -d "From=%2B14158675309" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls \
    -d "Url=http://demo.twilio.com/docs/voice.xml" \
    -d "To=client:tommy" \
    -d "From=%2B14158675309" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
Show Output
  • JSON
  • XML
{
	"sid": "CAa346467ca321c71dbd5e12f627deb854",
	"date_created": "Thu, 19 Aug 2010 00:12:15 +0000",
	"date_updated": "Thu, 19 Aug 2010 00:12:15 +0000",
	"parent_call_sid": null,
	"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"to": "client:tommy",
	"formatted_to": "tommy",
	"from": "+14158675309",
	"formatted_from": "(415) 867-5309",
	"phone_number_sid": "PNd6b0e1e84f7b117332aed2fd2e5bbcab",
	"status": "queued",
	"start_time": null,
	"end_time": null,
	"duration": null,
	"price": null,
	"direction": "outbound-api",
	"answered_by": null,
	"api_version": "2010-04-01",
	"forwarded_from": null,
	"caller_name": null,
	"uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAa346467ca321c71dbd5e12f627deb854.json",
	"subresource_uris": {
		"notifications": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAa346467ca321c71dbd5e12f627deb854\/Notifications.json",
		"recordings": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAa346467ca321c71dbd5e12f627deb854\/Recordings.json"
	}
}
<TwilioResponse>
	<Call>
		<Sid>CAa346467ca321c71dbd5e12f627deb854</Sid>
		<DateCreated>Thu, 19 Aug 2010 00:25:48 +0000</DateCreated>
		<DateUpdated>Thu, 19 Aug 2010 00:25:48 +0000</DateUpdated>
		<ParentCallSid/>
		<AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
		<To>client:tommy</To>
		<FormattedTo>tommy</FormattedTo>
		<From>+14158675309</From>
		<FormattedFrom>(415) 867-5309</FormattedFrom>
		<PhoneNumberSid></PhoneNumberSid>
		<Status>queued</Status>
		<StartTime/>
		<EndTime/>
		<Duration/>
		<Price/>
		<Direction>outbound-api</Direction>
		<AnsweredBy/>
		<ApiVersion>2010-04-01</ApiVersion>
		<ForwardedFrom/>
		<CallerName/>
		<Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAa346467ca321c71dbd5e12f627deb854</Uri>
		<SubresourceUris>
			<Notifications>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAa346467ca321c71dbd5e12f627deb854/Notifications</Notifications>
			<Recordings>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAa346467ca321c71dbd5e12f627deb854/Recordings</Recordings>
		</SubresourceUris>
	</Call>
</TwilioResponse>
Example 3

Make a call from 866-867-5309 to 415-555-1212 after dialing extension 1234#. Twilio will send a GET request to http://demo.twilio.com/docs/voice.xml to fetch TwiML to handle the call.

Example 3
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var options = new CallOptions();
    options.Url = "http://demo.twilio.com/docs/voice.xml";
    options.To = "+14155551212";
    options.SendDigits = "1234#";
    options.From = "+18668675309";
    options.Method = "GET";
    var call = twilio.InitiateOutboundCall(options);
    
    Console.WriteLine(call.Sid);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.CallFactory;
import com.twilio.sdk.resource.instance.Call;
import com.twilio.sdk.resource.list.CallList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the CallList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("Url", "http://demo.twilio.com/docs/voice.xml"));
    params.add(new BasicNameValuePair("To", "+14155551212"));
    params.add(new BasicNameValuePair("SendDigits", "1234#"));
    params.add(new BasicNameValuePair("From", "+18668675309"));
    params.add(new BasicNameValuePair("Method", "GET"));
    
    
    CallFactory callFactory = client.getAccount().getCallFactory();
    Call call = callFactory.create(params);
    System.out.println(call.getSid());
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.calls.create({
    url: "http://demo.twilio.com/docs/voice.xml",
    to: "+14155551212",
    sendDigits: "1234#",
    from: "+18668675309",
    method: "GET"
}, function(err, call) {
    process.stdout.write(call.sid);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "{{ auth_token }}"; 
$client = new Services_Twilio($sid, $token);

$call = $client->account->calls->create("+18668675309", "+14155551212", "http://demo.twilio.com/docs/voice.xml", array(
        "SendDigits" => "1234#",
    "Method" => "GET"
    ));
echo $call->sid;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

call = client.calls.create(url="http://demo.twilio.com/docs/voice.xml",
    to="+14155551212",
    send_digits="1234#",
    from_="+18668675309",
    method="GET")
print call.sid
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token

call = @client.account.calls.create(:url => "http://demo.twilio.com/docs/voice.xml",
    :to => "+14155551212",
    :send_digits => "1234#",
    :from => "+18668675309",
    :method => "GET")
puts call.start_time
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls.json \
    -d "Url=http://demo.twilio.com/docs/voice.xml" \
    -d "To=%2B14155551212" \
    -d "SendDigits=1234%23" \
    -d "From=%2B18668675309" \
    -d "Method=GET" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls \
    -d "Url=http://demo.twilio.com/docs/voice.xml" \
    -d "To=%2B14155551212" \
    -d "SendDigits=1234%23" \
    -d "From=%2B18668675309" \
    -d "Method=GET" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
Show Output
  • JSON
  • XML
{
	"sid": "CAc7a1fe47b14637f42fd94274d1907a1d",
	"date_created": "Thu, 19 Aug 2010 00:12:15 +0000",
	"date_updated": "Thu, 19 Aug 2010 00:12:15 +0000",
	"parent_call_sid": null,
	"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"to": "+14155551212",
	"formatted_to": "(415) 555-1212",
	"from": "+18668675309",
	"formatted_from": "(866) 867-5309",
	"phone_number_sid": "PNd6b0e1e84f7b117332aed2fd2e5bbcab",
	"status": "queued",
	"start_time": null,
	"end_time": null,
	"duration": null,
	"price": null,
	"direction": "outbound-api",
	"answered_by": null,
	"api_version": "2010-04-01",
	"forwarded_from": null,
	"caller_name": null,
	"uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAc7a1fe47b14637f42fd94274d1907a1d.json",
	"subresource_uris": {
		"notifications": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAc7a1fe47b14637f42fd94274d1907a1d\/Notifications.json",
		"recordings": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAc7a1fe47b14637f42fd94274d1907a1d\/Recordings.json"
	}
}
<TwilioResponse>
	<Call>
		<Sid>CAc7a1fe47b14637f42fd94274d1907a1d</Sid>
		<DateCreated>Thu, 19 Aug 2010 00:25:48 +0000</DateCreated>
		<DateUpdated>Thu, 19 Aug 2010 00:25:48 +0000</DateUpdated>
		<ParentCallSid/>
		<AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
		<To>+14155551212</To>
		<FormattedTo>(415) 555-1212</FormattedTo>
		<From>+18668675309</From>
		<FormattedFrom>(866) 867-5309</FormattedFrom>
		<PhoneNumberSid></PhoneNumberSid>
		<Status>queued</Status>
		<StartTime/>
		<EndTime/>
		<Duration/>
		<Price/>
		<Direction>outbound-api</Direction>
		<AnsweredBy/>
		<ApiVersion>2010-04-01</ApiVersion>
		<ForwardedFrom/>
		<CallerName/>
		<Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAc7a1fe47b14637f42fd94274d1907a1d</Uri>
		<SubresourceUris>
			<Notifications>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAc7a1fe47b14637f42fd94274d1907a1d/Notifications</Notifications>
			<Recordings>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAc7a1fe47b14637f42fd94274d1907a1d/Recordings</Recordings>
		</SubresourceUris>
	</Call>
</TwilioResponse>
Example 4

Make a call from 866-867-5309 to 415-555-1212, and POST all the call progress events to https://www.myapp.com/events.

Example 4
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example
{
  static void Main(string[] args)
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var options = new CallOptions();
    options.Url = "http://demo.twilio.com/docs/voice.xml";
    options.From = "+18668675309";
    options.Method = "GET";
    options.StatusCallback = "https://www.myapp.com/events";
    options.StatusCallbackMethod = "POST";
    options.StatusCallbackEvents = { "initiated", "ringing", "answered", "completed" };

    var call = twilio.InitiateOutboundCall(options);

    Console.WriteLine(call.Sid);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.CallFactory;
import com.twilio.sdk.resource.instance.Call;
import com.twilio.sdk.resource.list.CallList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example {

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the CallList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("Url", "http://demo.twilio.com/docs/voice.xml"));
    params.add(new BasicNameValuePair("To", "+14155551212"));
    params.add(new BasicNameValuePair("From", "+18668675309"));
    params.add(new BasicNameValuePair("Method", "GET"));
    params.add(new BasicNameValuePair("StatusCallback", "https://www.myapp.com/events"));
    params.add(new BasicNameValuePair("StatusCallbackMethod", "POST"));
    params.add(new BasicNameValuePair("StatusCallbackEvent", "initiated"));
    params.add(new BasicNameValuePair("StatusCallbackEvent", "ringing"));
    params.add(new BasicNameValuePair("StatusCallbackEvent", "answered"));
    params.add(new BasicNameValuePair("StatusCallbackEvent", "completed"));


    CallFactory callFactory = client.getAccount().getCallFactory();
    Call call = callFactory.create(params);
    System.out.println(call.getSid());
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.calls.create({
    url: "http://demo.twilio.com/docs/voice.xml",
    to: "+14155551212",
    from: "+18668675309",
    statusCallback: "https://www.myapp.com/events",
    statusCallbackMethod: "POST",
    statusCallbackEvent: ["initiated", "ringing", "answered", "completed"],
    method: "GET"
}, function(err, call) {
    process.stdout.write(call.sid);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$token = "{{ auth_token }}";
$client = new Services_Twilio($sid, $token);

$call = $client->account->calls->create("+18668675309", "+14155551212", "http://demo.twilio.com/docs/voice.xml", array(
    "Method" => "GET",
    "StatusCallback" => "https://www.myapp.com/events",
    "StatusCallbackMethod" => "POST",
    "StatusCallbackEvent" => array("initiated", "ringing", "answered", "completed"),
    ));
echo $call->sid;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

call = client.calls.create(
    url="http://demo.twilio.com/docs/voice.xml",
    to="+14155551212",
    from_="+18668675309",
    method="GET",
    status_callback="https://www.myapp.com/events",
    status_callback_method="POST",
    status_events=["initiated", "ringing", "answered", "completed"],
)
print call.sid
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token

call = @client.account.calls.create(:url => "http://demo.twilio.com/docs/voice.xml",
    :to => "+14155551212",
    :from => "+18668675309",
    :method => "GET",
    :status_callback => "https://www.myapp.com/events",
    :status_callback_method => "POST",
    :status_callback_event => ["initiated", "ringing", "answered", "completed"])
puts call.start_time
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls.json \
    -d "Url=http://demo.twilio.com/docs/voice.xml" \
    -d "To=%2B14155551212" \
    -d "From=%2B18668675309" \
    -d "Method=GET" \
    -d "StatusCallback=https://www.myapp.com/events" \
    -d "StatusCallbackMethod=POST" \
    -d "StatusCallbackEvent=initiated" \
    -d "StatusCallbackEvent=ringing" \
    -d "StatusCallbackEvent=answered" \
    -d "StatusCallbackEvent=completed" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls \
    -d "Url=http://demo.twilio.com/docs/voice.xml" \
    -d "To=%2B14155551212" \
    -d "From=%2B18668675309" \
    -d "Method=GET" \
    -d "StatusCallback=https://www.myapp.com/events" \
    -d "StatusCallbackMethod=POST" \
    -d "StatusCallbackEvent=initiated" \
    -d "StatusCallbackEvent=ringing" \
    -d "StatusCallbackEvent=answered" \
    -d "StatusCallbackEvent=completed" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
Show Output
  • JSON
  • XML
{
	"sid": "CAc7a1fe47b14637f42fd94274d1907a1d",
	"date_created": "Thu, 19 Aug 2010 00:12:15 +0000",
	"date_updated": "Thu, 19 Aug 2010 00:12:15 +0000",
	"parent_call_sid": null,
	"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"to": "+14155551212",
	"formatted_to": "(415) 555-1212",
	"from": "+18668675309",
	"formatted_from": "(866) 867-5309",
	"phone_number_sid": "PNd6b0e1e84f7b117332aed2fd2e5bbcab",
	"status": "queued",
	"start_time": null,
	"end_time": null,
	"duration": null,
	"price": null,
	"direction": "outbound-api",
	"answered_by": null,
	"api_version": "2010-04-01",
	"forwarded_from": null,
	"caller_name": null,
	"uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAc7a1fe47b14637f42fd94274d1907a1d.json",
	"subresource_uris": {
		"notifications": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAc7a1fe47b14637f42fd94274d1907a1d\/Notifications.json",
		"recordings": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAc7a1fe47b14637f42fd94274d1907a1d\/Recordings.json"
	}
}
<TwilioResponse>
	<Call>
		<Sid>CAc7a1fe47b14637f42fd94274d1907a1d</Sid>
		<DateCreated>Thu, 19 Aug 2010 00:25:48 +0000</DateCreated>
		<DateUpdated>Thu, 19 Aug 2010 00:25:48 +0000</DateUpdated>
		<ParentCallSid/>
		<AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
		<To>+14155551212</To>
		<FormattedTo>(415) 555-1212</FormattedTo>
		<From>+18668675309</From>
		<FormattedFrom>(866) 867-5309</FormattedFrom>
		<PhoneNumberSid></PhoneNumberSid>
		<Status>queued</Status>
		<StartTime/>
		<EndTime/>
		<Duration/>
		<Price/>
		<Direction>outbound-api</Direction>
		<AnsweredBy/>
		<ApiVersion>2010-04-01</ApiVersion>
		<ForwardedFrom/>
		<CallerName/>
		<Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAc7a1fe47b14637f42fd94274d1907a1d</Uri>
		<SubresourceUris>
			<Notifications>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAc7a1fe47b14637f42fd94274d1907a1d/Notifications</Notifications>
			<Recordings>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAc7a1fe47b14637f42fd94274d1907a1d/Recordings</Recordings>
		</SubresourceUris>
	</Call>
</TwilioResponse>
Example 5

Make a call from 866-867-5309 to 415-555-1212 and record each leg of the call in its own channel.

$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/AC5ef8732a3c49700934481addd5ce1659/Calls \
   -d "Url=http://demo.twilio.com/docs/voice.xml" \
   -d "To=%2B14155551212" \
   -d "From=%2B18668675309" \
   -d "Method=GET" \
   -d "Record=true" \
   -d "RecordingChannels=dual" \
   -d "RecordingStatusCallback=www.myexample.com" \
   -u 'AC5ef8732a3c49700934481addd5ce1659:{AuthToken}'

Output:

<TwilioResponse>
   <Call>
       <Sid>CAc7a1fe47b14637f42fd94274d1907a1d</Sid>
       <DateCreated>Thu, 19 Aug 2010 00:25:48 +0000</DateCreated>
       <DateUpdated>Thu, 19 Aug 2010 00:25:48 +0000</DateUpdated>
       <ParentCallSid/>
       <AccountSid>AC5ef872f6da5a21de157d80997a64bd33</AccountSid>
       <To>+14155551212</To>
       <FormattedTo>(415) 555-1212</FormattedTo>
       <From>+18668675309</From>
       <FormattedFrom>(866) 867-5309</FormattedFrom>
       <PhoneNumberSid></PhoneNumberSid>
       <Status>queued</Status>
       <StartTime/>
       <EndTime/>
       <Duration/>
       <Price/>
       <PriceUnit>USD</PriceUnit>
       <Direction>outbound-api</Direction>
       <AnsweredBy/>
       <ApiVersion>2010-04-01</ApiVersion>
       <ForwardedFrom/>
       <CallerName/>
 <Uri>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Calls/CAc7a1fe47b14637f42fd94274d1907a1d</Uri>
       <SubresourceUris>           <Notifications>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Calls/CAc7a1fe47b14637f42fd94274d1907a1d/Notifications</Notifications>
         <Recordings>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Calls/CAc7a1fe47b14637f42fd94274d1907a1d/Recordings</Recordings>
       </SubresourceUris>
   </Call>
</TwilioResponse>

Handling Possible Call Outcomes

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.

Answering Machines

IMPORTANT: Answering machine detection is an experimental feature, and support is limited. The downside of trying to detect a machine is that Twilio needs to listen to the first few seconds of audio after connecting a call. This usually results in a few seconds of delay before Twilio begins processing TwiML. If your application does not care about the human vs. machine distinction, then omit the 'IfMachine' parameter and Twilio will perform no such analysis.

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

The Default Behavior

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.

Hanging Up

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.

Continuing If A Machine Answers

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 <Play> or <Say> content. Keep in mind that if a machine answers you'll want to avoid using <Gather> or <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.