<Dial><Application> Usage

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.

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.

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.

Expand image

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.

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.