TwiML™ Voice: <Application>
The <Dial> verb’s <Application> noun allows you to connect a call to another Twilio account without losing the original call leg's context (e.g. the original "From" number). Rather than dialing a phone number or SIP endpoint, you can <Dial> a TwiML App directly with <Dial><Application>. <Dial><Application> also supports sending custom parameters using <Parameter>.
You can also direct a call to a TwiML App within your TwiML account using <Dial><Application>.
Note: Simultaneous dialing is NOT supported when performing <Dial><Application>.
This page covers <Application>'s attributes, supported TwiML nouns, and supported <Dial> attributes.
To learn more about how use <Dial><Application>, how Twilio handles <Dial><Application> instructions, and an example scenario, go to the <Dial><Application> Usage page.
Table of Contents
Basic usage
The TwiML example below shows the most basic use of <Dial><Application>.
<Application> attributes
<Application> supports the following attributes:
Attribute | Allowed Values | Default Value |
optional |
a string up to 256 characters in length | The Twilio Account SID that is providing the <Dial><Application> TwiML instructions |
optional |
true , false |
false |
customerId
<Application>'s customerId
attribute allows you to set an identifier for the "sender" of the <Dial><Application>. The customerId
will be sent as a parameter in Twilio's request to the TwiML App's Voice Request URL.
The customerId
attribute can be any string up to 256 characters.
The default value of the customerId
attribute is the Account SID associated with the <Dial><Application> TwiML.
The customerId
attribute is optional.
copyParentTo
<Application>'s copyParentTo
attribute, when set to true
, uses the parent call's To
parameter as the To
parameter in the request to the TwiML App's Voice URL.
When the copyParentTo
value is false
, the To
field is the dialed TwiML App's SID.
The default value of the copyParentTo
attribute is false
.
The copyParentTo
attribute is optional.
<Application> Nouns
<Application> accepts nested <ApplicationSid> and <Parameter> nouns.
<ApplicationSid> is required, while <Parameter> is optional.
<ApplicationSid>
In order to use <Dial><Application>, an <ApplicationSid> noun must be nested within <Application>'s opening and closing tags.
Between <ApplicationSid>'s opening and closing tags, specify the SID of the TwiML App that you wish to dial.
<Parameter>
<Dial><Application> supports <Parameter> nouns, which allows you to pass custom parameters in Twilio's request to the receiving TwiML App's Voice URL.
You may nest one or more <Parameter> nouns within <Application>.
Each <Parameter> noun nested inside <Application> represents a key/value pair of information you wish to send in Twilio's request to the TwiML App's Voice URL.
The <Parameter> noun has two attributes:
name
- the name of your custom parametervalue
- the value of your custom parameter
Each custom parameter is passed as a request parameter in Twilio's request to the TwiML App's Voice URL. In the request, each custom parameter's name
is prefixed with Param_
.
The TwiML example below shows how to use <Dial><Application> with nested <Parameter> nouns.
For the example above, the body of Twilio's request to the TwiML App's Voice URL will contain Param_AccountNumber: "12345"
and Param_TicketNumber: "9876"
.
Supported <Dial> attributes
<Application> supports the following <Dial> attributes:
- action
- callerId
- answerOnBridge
- callReason
- timeLimit
- timeout
- method
- hangupOnStar
- record
- recordingStatusCallback
- recordingStatusCallbackMethod
- recordingStatusCallbackEvent
- recordingTrack
- ringTone
<Dial><Application> supports sending custom parameters from the dialed party back to the originating <Dial>'s action
URL. Learn more on the <Dial><Application> Usage page.
Note: REFER support via referUrl
is NOT supported when using <Dial><Application>.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.