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

Table of Contents

• Basic usage
• <Application> attributes
  • customerId
  • copyParentTo
• Supported TwiML nouns
  • <ApplicationSid>
  • <Parameter>
• Supported <Dial> attributes

Basic usage

The TwiML example below shows the most basic use of <Dial><Application>.

<Application> attributes

<Application> supports the following attributes:

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 parameter
• value - 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>.