# \<Dial>\<Application> Usage

The [`<Dial>`](/docs/voice/twiml/dial) verb's [`<Application>`](/docs/voice/twiml/dial/application) noun lets you connect a call to another Twilio account without losing the original call leg's context (for example, the original `From` number). Rather than dialing a phone number or SIP endpoint, you can `<Dial>` a TwiML App directly with `<Dial><Application>`.

You can manage TwiML Apps through the REST API using the [Application Resource](/docs/usage/api/applications), in the [Twilio Console](https://1console.twilio.com/go?to=/account/__account__/us1/voice/twiml-apps/), or in the [legacy Console](https://console.twilio.com/?frameUrl=/console/voice/twiml/apps).

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 with a Voice URL that returns TwiML instructions.

   * If you want 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

The receiving TwiML App must be configured to allow calls from a different Twilio account through `<Dial><Application>`. You can configure the TwiML App in the Twilio Console or through 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 Console

To allow inbound `<Dial><Application>` calls from a different Twilio account, follow these steps:

## Console

1. In the [Twilio Console](https://1console.twilio.com/), go to **Develop** > **TwiML apps**.
2. Select the TwiML app you want to modify.
3. On the **Voice** tab, under **Settings**, select **Allow** for **Allow Application Dialing from other Twilio Accounts**.
4. Click **Save**.

## Legacy Console

1. Go to **Voice** > **Manage** > [**TwiML apps**](https://console.twilio.com/?frameUrl=/console/voice/twiml/apps).
2. Select the TwiML app you want to modify.
3. Select **Allow Application Dialing from other Twilio Accounts**.
4. Click **Save**.

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