Skip to contentSkip to navigationSkip to topbar
On this page

<Dial><Application> Usage


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> TwiML App directly with <Dial><Application>.

This page covers how to use <Dial><Application>, how Twilio handles <Dial><Application> instructions, returning custom parameters to the originating <Dial>'s action URL, and an example scenario.

If you want to learn more about <Application>'s TwiML attributes, supported TwiML nouns, and supported <Dial> attributes, go to the <Application> TwiML page.


Usage

usage page anchor

In order to use <Dial><Application>, you must have the following:

  1. An existing Programmable Voice application with a call path that leads to <Dial><Application> TwiML instructions.

  2. A TwiML App with a Voice URL that returns TwiML instructions.

    • If you wish to transfer calls to another Twilio account, this TwiML App must exist within the "receiving" Twilio account, and must be configured to allow <Dial><Application> requests from a different Twilio account.
    • Transferring calls within the same Twilio account requires no additional configuration.

Accept calls from a different Twilio account

accept-calls-from-a-different-twilio-account page anchor

The receiving TwiML App must be configured to allow calls from a different Twilio via <Dial><Application>. You can configure the TwiML App in your Twilio Console or via the REST API.

(warning)

Warning

It is your responsibility to secure and authenticate inbound calls to a TwiML App if you accept calls from outside your Twilio account.

Enabling inbound calls via <Dial><Application> opens up the TwiML App to calls from any Twilio customer. You should only give the receiving TwiML App's SID to the party/parties from which you intend to receive calls. You should implement some sort of authentication to verify calls are coming to your TwiML App from a trusted party.

Configure your TwiML App in the Console

configure-your-twiml-app-in-the-console page anchor

Follow the steps listed below to allow inbound <Dial><Application> calls from a different Twilio account.

  1. In the Console, navigate to the TwiML App's page. In the left navigation pane, under the Develop tab, click on Voice > Manage > TwiML apps and click on the TwiML App you wish to modify.
  2. On the TwiML App's page in the Twilio Console, check the box for Allow Application Dialing for other Twilio Accounts.
  3. Click the Save button.
Checkbox for 'Allow Application Dialing from other Twilio Accounts' checked on a TwiML App page in the Twilio Console.

Configure your TwiML App with the REST API

configure-your-twiml-app-with-the-rest-api page anchor

Within Twilio's REST API, a TwiML App is called an Application Resource. If you wish to configure TwiML Apps to allow inbound <Dial><Application> calls from a different Twilio account, set the PublicApplicationConnectEnabled property to true on the TwiML App's Application Resource.

You can either update an existing Application Resource with PublicApplicationConnectEnabled set to true or you can set this property to true when creating a new Application Resource.


Your company has two, separate Twilio accounts:

  • Account A - handles inbound calls with an IVR
  • Account B - handles all payments using <Pay>

Account A has a path within its IVR to direct callers to the following TwiML instructions:

1
<Response>
2
<Dial action="https://example.com/account-a-action-url">
3
<Application>
4
<ApplicationSid>AP1234567890abcdef1234567890abcd</ApplicationSid>
5
</Application>
6
</Dial>
7
</Response>

Account B has a TwiML App with a SID of AP1234567890abcdef1234567890abcd. The TwiML App is configured to allow incoming calls from external Twilio accounts. The TwiML App's Voice URL returns the following TwiML:

1
<Response>
2
<Pay paymentAmount="12.23" />
3
</Response>

Your company's customer, Michael, has dialed a Twilio Phone Number owned by Account A. This creates the "parent call".

Michael needs to be connected to Account B so that he can enter his payment information. To achieve this, Account A's IVR leads Michael's call to the <Dial><Application> TwiML instructions above.

When Twilio executes these <Dial><Application> instructions, the following occurs:

  1. Within Account A, Twilio creates a new call leg. This is called the "child call" of the parent call.

    • Within Account A's Call Logs, this child call has the following properties:

      • Direction: Outgoing Dial
      • From: [Michael's phone number]
      • To: Account B's TwiML App SID.
  2. In Account B, Twilio creates a new, incoming call.

    • Within Account B's Call Logs, this call has the following properties:

      • Direction: Incoming
      • From: [Michael's phone number]
      • To: Account B's TwiML App SID.
  3. Within Account B, Twilio sends a request to Account B's TwiML App's Voice URL.

  4. The endpoint at Account B's TwiML App's Voice URL responds with TwiML instructions (the <Pay> instructions shown above).

  5. Twilio executes the TwiML instructions, and Michael hears prompts to enter his payment information.

Return custom parameters to the <Dial> action URL

return-custom-parameters-to-the-dial-action-url page anchor

At the end of a <Dial> instruction (i.e. the incoming call in Account B ends and/or the child call in Account A ends), Twilio sends a request to the <Dial> verb's action URL.

If the caller remains on the line, the parent call in Account A can continue as long as the action URL returns TwiML instructions to Twilio.

TwiML Apps that receive calls via <Dial><Application> can send custom parameters in the request to the action URL by using <Hangup><Parameter> or <Reject><Parameter>.

To explain this using the scenario from above, assume that instead of <Pay> instructions, Account B's TwiML App's Voice URL returned the following TwiML instructions:

1
<Response>
2
<Say>We're sorry. All of our agents are busy right now.</Say>
3
<Say>We will call you back as soon as possible.</Say>
4
<Say>Please stay on the line to be redirected to the main menu.</Say>
5
<Hangup>
6
<Parameter name="payment_collected" value="false" />
7
</Hangup>
8
</Response>

After Twilio executes these instructions, Account A's <Dial> action URL (https://example.com/account-a-action-url) will receive a request from Twilio. The request will contain ReturnParam_payment_collected: "false".

Account A can use these custom parameters to dynamically create further TwiML instructions for Michael, or to log relevant information internally.

<Hangup><Parameter> and <Reject><Parameter>

Typically, <Hangup> and <Reject> are self-closing TwiML tags, meaning that you only use one XML tag in your TwiML, e.g. <Hangup /> and <Reject />.

If you wish to use <Parameter> within <Hangup> or <Reject>, you will need to use an opening and closing tag to surround the <Parameter>. See examples of this below.

Note: If using <Reject><Parameter>, the caller may not stay on the call, since they will hear either a busy signal or a standard not-in-service message. You can still send information back to the <Dial> action URL for logging purposes, but without prompting the caller to stay on the line, the parent call may end.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.