Create a new outgoing call to phones
A Call is an object that represents a connection between a telephone and Twilio.
Create a new outgoing call to phones, SIP-enabled endpoints or Twilio Client connections
Path parameters
-
The SID of the Account that will create the resource.
Body
-
ApplicationSid string
The SID of the Application resource that will handle the call, if the call will be handled by an application.
Minimum length is
34
, maximum length is34
. Format should match the following pattern:^AP[0-9a-fA-F]{32}$
. -
AsyncAmd string
Select whether to perform answering machine detection in the background. Default, blocks the execution of the call until Answering Machine Detection is completed. Can be:
true
orfalse
. -
AsyncAmdStatusCallback string(uri)
The URL that we should call using the
async_amd_status_callback_method
to notify customer application whether the call was answered by human, machine or fax. -
AsyncAmdStatusCallbackMethod string(http-method)
The HTTP method we should use when calling the
async_amd_status_callback
URL. Can be:GET
orPOST
and the default isPOST
.Values are
HEAD
,GET
,POST
,PATCH
,PUT
, orDELETE
. -
Byoc string
The SID of a BYOC (Bring Your Own Carrier) trunk to route this call with. Note that
byoc
is only meaningful whento
is a phone number; it will otherwise be ignored. (Beta)Minimum length is
34
, maximum length is34
. Format should match the following pattern:^BY[0-9a-fA-F]{32}$
. -
CallReason string
The Reason for the outgoing call. Use it to specify the purpose of the call that is presented on the called party's phone. (Branded Calls Beta)
-
CallToken string
A token string needed to invoke a forwarded call. A call_token is generated when an incoming call is received on a Twilio number. Pass an incoming call's call_token value to a forwarded call via the call_token parameter when creating a new call. A forwarded call should bear the same CallerID of the original incoming call.
-
CallerId string
The phone number, SIP address, or Client identifier that made this call. Phone numbers are in E.164 format (e.g., +16175551212). SIP addresses are formatted as
name@company.com
. -
FallbackMethod string(http-method)
The HTTP method that we should use to request the
fallback_url
. Can be:GET
orPOST
and the default isPOST
. If anapplication_sid
parameter is present, this parameter is ignored.Values are
HEAD
,GET
,POST
,PATCH
,PUT
, orDELETE
. -
FallbackUrl string(uri)
The URL that we call using the
fallback_method
if an error occurs when requesting or executing the TwiML aturl
. If anapplication_sid
parameter is present, this parameter is ignored. -
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. If the
to
parameter is a phone number,From
must also be a phone number. -
MachineDetection string
Whether to detect if a human, answering machine, or fax has picked up the call. Can be:
Enable
orDetectMessageEnd
. UseEnable
if you would like us to returnAnsweredBy
as soon as the called party is identified. UseDetectMessageEnd
, if you would like to leave a message on an answering machine. Ifsend_digits
is provided, this parameter is ignored. For more information, see Answering Machine Detection. -
MachineDetectionSilenceTimeout integer
The number of milliseconds of initial silence after which an
unknown
AnsweredBy result will be returned. Possible Values: 2000-10000. Default: 5000. -
The number of milliseconds of silence after speech activity at which point the speech activity is considered complete. Possible Values: 500-5000. Default: 1200.
-
MachineDetectionSpeechThreshold integer
The number of milliseconds that is used as the measuring stick for the length of the speech activity, where durations lower than this value will be interpreted as a human and longer than this value as a machine. Possible Values: 1000-6000. Default: 2400.
-
MachineDetectionTimeout integer
The number of seconds that we should attempt to detect an answering machine before timing out and sending a voice request with
AnsweredBy
ofunknown
. The default timeout is 30 seconds. -
Method string(http-method)
The HTTP method we should use when calling the
url
parameter's value. Can be:GET
orPOST
and the default isPOST
. If anapplication_sid
parameter is present, this parameter is ignored.Values are
HEAD
,GET
,POST
,PATCH
,PUT
, orDELETE
. -
Record boolean
Whether to record the call. Can be
true
to record the phone call, orfalse
to not. The default isfalse
. Therecording_url
is sent to thestatus_callback
URL. -
RecordingChannels string
The number of channels in the final recording. Can be:
mono
ordual
. The default ismono
.mono
records both legs of the call in a single channel of the recording file.dual
records each leg to a separate channel of the recording file. The first channel of a dual-channel recording contains the parent call and the second channel contains the child call. -
RecordingStatusCallback string
The URL that we call when the recording is available to be accessed.
-
RecordingStatusCallbackEvent array[string]
The recording status events that will trigger calls to the URL specified in
recording_status_callback
. Can be:in-progress
,completed
andabsent
. Defaults tocompleted
. Separate multiple values with a space. -
RecordingStatusCallbackMethod string(http-method)
The HTTP method we should use when calling the
recording_status_callback
URL. Can be:GET
orPOST
and the default isPOST
.Values are
HEAD
,GET
,POST
,PATCH
,PUT
, orDELETE
. -
RecordingTrack string
The audio track to record for the call. Can be:
inbound
,outbound
orboth
. The default isboth
.inbound
records the audio that is received by Twilio.outbound
records the audio that is generated from Twilio.both
records the audio that is received and generated by Twilio. -
SendDigits string
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, and then dial extension 1234 followed by the pound key, the value of this parameter would beww1234#
. Remember to URL-encode this string, since the '#
' character has special meaning in a URL. If bothSendDigits
andMachineDetection
parameters are provided, thenMachineDetection
will be ignored. -
SipAuthPassword string
The password required to authenticate the user account specified in
sip_auth_username
. -
SipAuthUsername string
The username used to authenticate the caller making a SIP call.
-
StatusCallback string(uri)
The URL we should call using the
status_callback_method
to send status information to your application. If nostatus_callback_event
is specified, we will send thecompleted
status. If anapplication_sid
parameter is present, this parameter is ignored. URLs must contain a valid hostname (underscores are not permitted). -
StatusCallbackEvent array[string]
The call progress events that we will send to the
status_callback
URL. Can be:initiated
,ringing
,answered
, andcompleted
. If no event is specified, we send thecompleted
status. If you want to receive multiple events, specify each one in a separatestatus_callback_event
parameter. See the code sample for monitoring call progress. If anapplication_sid
is present, this parameter is ignored. -
StatusCallbackMethod string(http-method)
The HTTP method we should use when calling the
status_callback
URL. Can be:GET
orPOST
and the default isPOST
. If anapplication_sid
parameter is present, this parameter is ignored.Values are
HEAD
,GET
,POST
,PATCH
,PUT
, orDELETE
. -
TimeLimit integer
The maximum duration of the call in seconds. Constraints depend on account and configuration.
-
Timeout integer
The integer number of seconds that we should allow the phone to ring before assuming there is no answer. The default is
60
seconds and the maximum is600
seconds. For some call flows, we will add a 5-second buffer to the timeout value you provide. For this reason, a timeout value of 10 seconds could result in an actual timeout closer to 15 seconds. You can set this to a short time, such as15
seconds, to hang up before reaching an answering machine or voicemail. -
The phone number, SIP address, or client identifier to call.
-
Trim string
Whether to trim any leading and trailing silence from the recording. Can be:
trim-silence
ordo-not-trim
and the default istrim-silence
. -
Twiml string
TwiML instructions for the call Twilio will use without fetching Twiml from url parameter. If both
twiml
andurl
are provided thentwiml
parameter will be ignored. Max 4000 characters. -
Url string(uri)
The absolute URL that returns the TwiML instructions for the call. We will call this URL using the
method
when the call connects. For more information, see the Url Parameter section in Making Calls.
curl \
-X POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls.json \
--user "username:password" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'ApplicationSid=string&AsyncAmd=string&AsyncAmdStatusCallback=https%3A%2F%2Fexample.com&AsyncAmdStatusCallbackMethod=HEAD&Byoc=string&CallReason=string&CallToken=string&CallerId=string&FallbackMethod=HEAD&FallbackUrl=https%3A%2F%2Fexample.com&From=string&MachineDetection=string&MachineDetectionSilenceTimeout=42&MachineDetectionSpeechEndThreshold=42&MachineDetectionSpeechThreshold=42&MachineDetectionTimeout=42&Method=HEAD&Record=true&RecordingChannels=string&RecordingStatusCallback=string&RecordingStatusCallbackEvent=string&RecordingStatusCallbackMethod=HEAD&RecordingTrack=string&SendDigits=string&SipAuthPassword=string&SipAuthUsername=string&StatusCallback=https%3A%2F%2Fexample.com&StatusCallbackEvent=string&StatusCallbackMethod=HEAD&TimeLimit=42&Timeout=42&To=string&Trim=string&Twiml=string&Url=https%3A%2F%2Fexample.com'
{
"ApplicationSid": "string",
"AsyncAmd": "string",
"AsyncAmdStatusCallback": "https://example.com",
"AsyncAmdStatusCallbackMethod": "HEAD",
"Byoc": "string",
"CallReason": "string",
"CallToken": "string",
"CallerId": "string",
"FallbackMethod": "HEAD",
"FallbackUrl": "https://example.com",
"From": "string",
"MachineDetection": "string",
"MachineDetectionSilenceTimeout": 42,
"MachineDetectionSpeechEndThreshold": 42,
"MachineDetectionSpeechThreshold": 42,
"MachineDetectionTimeout": 42,
"Method": "HEAD",
"Record": true,
"RecordingChannels": "string",
"RecordingStatusCallback": "string",
"RecordingStatusCallbackEvent": [
"string"
],
"RecordingStatusCallbackMethod": "HEAD",
"RecordingTrack": "string",
"SendDigits": "string",
"SipAuthPassword": "string",
"SipAuthUsername": "string",
"StatusCallback": "https://example.com",
"StatusCallbackEvent": [
"string"
],
"StatusCallbackMethod": "HEAD",
"TimeLimit": 42,
"Timeout": 42,
"To": "string",
"Trim": "string",
"Twiml": "string",
"Url": "https://example.com"
}
{
"ApplicationSid": "string",
"AsyncAmd": "string",
"AsyncAmdStatusCallback": "https://example.com",
"AsyncAmdStatusCallbackMethod": "HEAD",
"Byoc": "string",
"CallReason": "string",
"CallToken": "string",
"CallerId": "string",
"FallbackMethod": "HEAD",
"FallbackUrl": "https://example.com",
"From": "string",
"MachineDetection": "string",
"MachineDetectionSilenceTimeout": 42,
"MachineDetectionSpeechEndThreshold": 42,
"MachineDetectionSpeechThreshold": 42,
"MachineDetectionTimeout": 42,
"Method": "HEAD",
"Record": true,
"RecordingChannels": "string",
"RecordingStatusCallback": "string",
"RecordingStatusCallbackEvent": [
"string"
],
"RecordingStatusCallbackMethod": "HEAD",
"RecordingTrack": "string",
"SendDigits": "string",
"SipAuthPassword": "string",
"SipAuthUsername": "string",
"StatusCallback": "https://example.com",
"StatusCallbackEvent": [
"string"
],
"StatusCallbackMethod": "HEAD",
"TimeLimit": 42,
"Timeout": 42,
"To": "string",
"Trim": "string",
"Twiml": "string",
"Url": "https://example.com"
}
{
"account_sid": "string",
"answered_by": "string",
"api_version": "string",
"caller_name": "string",
"date_created": "string",
"date_updated": "string",
"direction": "string",
"duration": "string",
"end_time": "string",
"forwarded_from": "string",
"from": "string",
"from_formatted": "string",
"group_sid": "string",
"parent_call_sid": "string",
"phone_number_sid": "string",
"price": "string",
"price_unit": "string",
"queue_time": "string",
"sid": "string",
"start_time": "string",
"status": "queued",
"subresource_uris": {},
"to": "string",
"to_formatted": "string",
"trunk_sid": "string",
"uri": "https://example.com"
}
{
"account_sid": "string",
"answered_by": "string",
"api_version": "string",
"caller_name": "string",
"date_created": "string",
"date_updated": "string",
"direction": "string",
"duration": "string",
"end_time": "string",
"forwarded_from": "string",
"from": "string",
"from_formatted": "string",
"group_sid": "string",
"parent_call_sid": "string",
"phone_number_sid": "string",
"price": "string",
"price_unit": "string",
"queue_time": "string",
"sid": "string",
"start_time": "string",
"status": "queued",
"subresource_uris": {},
"to": "string",
"to_formatted": "string",
"trunk_sid": "string",
"uri": "https://example.com"
}