# \<Dial>\<Application> Usage

The [`<Dial>`](/docs/voice/twiml/dial) verb's [`<Application>`](/docs/voice/twiml/dial/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](https://console.twilio.com/?frameUrl=/console/voice/twiml/apps) directly with `<Dial><Application>`.

[TwiML Apps](https://console.twilio.com/?frameUrl=/console/voice/twiml/apps) can be managed in the Twilio Console or via the REST API using the [Application Resource](/docs/usage/api/applications).

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, see [`<Application>` TwiML](/docs/voice/twiml/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](https://console.twilio.com/?frameUrl=/console/voice/twiml/apps) with a Voice URL that returns TwiML instructions.

   * If you wish to transfer calls to another Twilio account, this [TwiML App](https://console.twilio.com/?frameUrl=/console/voice/twiml/apps) 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

The receiving [TwiML App](https://console.twilio.com/?frameUrl=/console/voice/twiml/apps) must be configured to allow calls from a different Twilio via `<Dial><Application>`. You can configure the [TwiML App](https://console.twilio.com/?frameUrl=/console/voice/twiml/apps) in your Twilio Console or via the REST API using the [Application Resource](/docs/usage/api/applications).

> \[!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

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](https://console.twilio.com/?frameUrl=/console/voice/twiml/apps)'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](https://console.twilio.com/?frameUrl=/console/voice/twiml/apps)'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 TwiML App Connect Success page.](https://docs-resources.prod.twilio.com/b173a7b7ff2c5529608645a351136b78210dcb78f35d0322cc70d505ca9a1701.png)

### Configure your TwiML App with the REST API

Within Twilio's REST API, a TwiML App is called an [Application Resource](/docs/usage/api/applications). 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](/docs/usage/api/applications).

You can either [update an existing Application Resource](/docs/usage/api/applications#update-an-application-resource) with `PublicApplicationConnectEnabled` set to `true` or you can set this property to `true` when [creating a new Application Resource](/docs/usage/api/applications#update-an-application-resource).

## Example scenario

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:

```xml
<Response>
  <Dial action="https://example.com/account-a-action-url">
    <Application>
      <ApplicationSid>AP1234567890abcdef1234567890abcd</ApplicationSid>
    </Application>
  </Dial>
</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:

```xml
<Response>
  <Pay paymentAmount="12.23" />
</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>` verb's `action` URL

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:

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

After Twilio executes these instructions, **Account** **A**'s `<Dial>`'s `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>`s `action` URL for logging purposes, but without prompting the caller to stay on the line, the parent call may end.