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.
In order to use <Dial><Application>, you must have the following:
A TwiML App with a Voice URL that returns TwiML instructions.
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.
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.
Follow the steps listed below to allow inbound <Dial><Application> calls from a different Twilio account.
_10<Response>_10 <Dial action="https://example.com/account-a-action-url">_10 <Application>_10 <ApplicationSid>AP1234567890abcdef1234567890abcd</ApplicationSid>_10 </Application>_10 </Dial>_10</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:
_10<Response>_10 <Pay paymentAmount="12.23" />_10</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:
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:
In Account B, Twilio creates a new, incoming call.
Within Account B's Call Logs, this call has the following properties:
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:
_10<Response>_10 <Say>We're sorry. All of our agents are busy right now.</Say>_10 <Say>We will call you back as soon as possible.</Say>_10 <Say>Please stay on the line to be redirected to the main menu.</Say>_10 <Hangup>_10 <Parameter name="payment_collected" value="false" />_10 </Hangup>_10</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.