TwiML™ Voice: <Dial>

<Dial> supports the following attributes that change its behavior:

Use one or more of these attributes in a <Dial> verb like so:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial timeout="10" record="true">415-123-4567</Dial>
4
</Response>

The action attribute accepts a URL as its argument. This URL tells Twilio where to make a POST or GET request after the dialed call ends.

Twilio's request to this URL will include the following parameters:

If you <Dial> a <Queue>, Twilio will pass additional parameters to your action URL. Read the in-depth <Queue> documentation for more details.

If you do not provide an action URL, <Dial> will finish and Twilio will move on to the next TwiML verb in the document. If there is no further verb, Twilio will end the phone call. Note that this is different from the behavior of <Record> and <Gather>.

Back to attributes list

If you specify an action URL, Twilio will always pass along the status of the <Dial> attempt.

Possible DialCallStatus values are:

Back to attributes list

If <Dial> is the first TwiML verb in your TwiML document, answerOnBridge="true" will cause the inbound call to ring until the dialed number answers.

If your inbound call is a SIP call, Twilio will send a 180 or 183 to your SIP server once it connects to Twilio. It will wait until the <Dial> call connects to return a 200.

Back to attributes list

When you use <Dial> in your response to Twilio's inbound call request, the dialed party sees the inbound caller's number as the caller ID.

For example:

1. Someone with a caller ID of 1-415-123-4567 calls your Twilio number.
2. You tell Twilio to execute a <Dial> verb to 1-858-987-6543 to handle the inbound call.
3. The called party (1-858-987-6543) will see 1-415-123-4567 as the caller ID on the incoming call.

When using the <Number> noun, and specifying a callerId on your <Dial>, you can set a different caller ID than the default. You may change the phone number that the called party sees to one of the following:

• Either the To or From number provided in Twilio's TwiML request to your app.
• Any incoming phone number you have purchased from Twilio.
• Any phone number you have verified with Twilio.

If you are dialing a <Client>, you can also set a valid client identifier as the callerId attribute. For instance, if you've set up a client for incoming calls and you are dialing that client, you could set the callerId attribute to client:joey.

If you are dialing a <Sip> endpoint, enter any alphanumeric string as the callerId. Optionally include the following characters: +, -, _, and ., but no whitespace.

In the following example, we use <Dial> to call a phone number from a Voice SDK Device instance:

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
const dial = response.dial({
6
    callerId: '+15551112222'
7
});
8
dial.number('+15558675310');
9

10
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial callerId="+15551112222">
4
        <Number>+15558675310</Number>
5
    </Dial>
6
</Response>

Back to attributes list

The hangupOnStar attribute lets the initial caller hang up on the called party by pressing the '*' key on their phone.

When two parties are connected using <Dial>, Twilio blocks execution of further verbs until the caller or called party hangs up. The hangupOnStar feature allows the initial caller to hang up on the party they called without having to hang up the phone (which would end the TwiML processing session).

When the caller presses '*', Twilio will hang up on the called party. If an action URL was provided, Twilio submits a DialCallStatus to that URL and processes the response. When calling a conference, the DialCallStatus will be answered. All other call types will have a completed DialCallStatus.

If no action was provided, Twilio continues on to the next verb in the current TwiML document.

Back to attributes list

The method attribute accepts either GET or POST. This tells Twilio whether to request the action URL via HTTP GET or POST, with POST as its default value.

In the following example, we've provided an action URL and specified GET as the method:

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
response.dial({
6
    action: '/handleDialCallStatus',
7
    method: 'GET'
8
}, '415-123-4567');
9
response.say('I am unreachable');
10

11
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<!-- page located at http://example.com/dial_callstatus.xml -->
3
<Response>
4
    <Dial action="/handleDialCallStatus" method="GET">
5
        415-123-4567
6
    </Dial>
7
    <Say>I am unreachable</Say>
8
</Response>

This code will <Dial> to connect the initial caller to the phone number 415-123-4567.

When the<Dial> call ends, Twilio will send a GET request to our action URL. This request will include the DialCallStatus parameter that tells us the status of that <Dial> call.

Our web application hosted at this action URL can now look at the DialCallStatus and send a response to Twilio telling it what to do next.

Back to attributes list

The record attribute lets you record both legs of a call within the associated <Dial> verb. Recordings are available in two options: mono-channel or dual-channel.

In mono-channel recordings, both legs of the call are mixed down into a single channel within one recording file.

For mono-channel record options, you can choose either:

• record-from-answer, which will start the recording as soon as the call is answered.
• record-from-ringing, which will start the recording when the ringing begins (before the recipient answers the call).

With dual-channel recordings, both legs use separate channels within a single recording file.

For dual-channel record options, you can choose either:

• record-from-answer-dual, which will start the recording as soon as the call is answered.
• record-from-ringing-dual, which will start the recording when the ringing begins (before the recipient answers the call).

The parent call will always be in the first channel and the child call will always be in the second channel of a dual-channel recording.

If a dual-channel recording option is used for a <Dial> with a nested <Conference>, the resulting recording file will have two channels. The parent leg (inbound caller) is represented in the first channel. The second channel includes the audio coming downstream from the conference.

Back to attributes list

The recordingStatusCallback attribute takes a relative or absolute URL as an argument. If you've requested recording for this <Dial>, this URL tells Twilio where to make its GET or POST request when the recording is available to access.

Twilio will pass the following parameters with its request to your recordingStatusCallback URL:

Back to attributes list

The recordingStatusCallbackEvent allows you to specify which recording status changes should generate a webhook to the URL specified in the recordingStatusCallback attribute. The available values are:

• in-progress: the recording has started.
• completed: the recording is complete and available.
• absent: the recording is absent and inaccessible.

To specify more than one value, separate each with a space. The default value is: completed.

The following example specifies that we want each participant on the <Dial> call to be represented in their own channel of the final recording, and that recording should begin when the call begins to ring.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
const dial = response.dial({
6
    record: 'record-from-ringing-dual',
7
    recordingStatusCallback: 'www.myexample.com'
8
});
9
dial.number('+15558675310');
10

11
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial record="record-from-ringing-dual"
4
          recordingStatusCallback="www.myexample.com">
5
        <Number>+15558675310</Number>
6
    </Dial>
7
</Response>

Back to attributes list

The recordingTrack attribute lets you select whether the inbound, outbound or both audio tracks of the call should be recorded. Inbound track represents the audio received by Twilio, and the outbound track represents the audio that Twilio generates on the call. The default value is both and it will record the audio that is received and generated by Twilio.

Back to attributes list

If the called party sends a SIP REFER request, a request from Twilio will be sent to your referUrl. Your application must respond with how to handle the transfer. Learn more about Inbound SIP REFER to Twilio.

The following parameters are added to the standard Twilio Voice Webhook Request:

1
const VoiceResponse = require("twilio").twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const dial = response.dial({
5
  referUrl: "https://example.com/handler",
6
});
7
dial.sip(
8
  "sip:AgentA@xyz.sip.us1.twilio.com?User-to-User=123456789%3Bencoding%3Dhex&X-Name=Agent%2C+A"
9
);
10

11
console.log(response.toString());

1
<Response>
2
    <Dial referUrl="https://example.com/handler">
3
        <Sip>sip:AgentA@xyz.sip.us1.twilio.com?User-to-User=123456789%3Bencoding%3Dhex&amp;X-Name=Agent%2C+A</Sip>
4
    </Dial>
5
</Response>

Back to attributes list

The referMethod attribute accepts either GET or POST. This tells Twilio whether to request the action URL via HTTP GET or POST, with POST as its default value.

Back to attributes list

Ringtone allows you to override the ringback tone that Twilio will play back to the caller while executing a <Dial>.

If not specified, Twilio will play ringback or pass ringback from the carrier (if provided). This works automatically but there may be cases where an override is desired.

Accepted values are: at, au, bg, br, be, ch, cl, cn, cz, de, dk, ee, es, fi, fr, gr, hu, il, in, it, lt, jp, mx, my, nl, no, nz, ph, pl, pt, ru, se, sg, th, uk, us, us-old, tw, ve, za.

Note: If you are dialing a <Sip> endpoint, ringTone will only work as expected if you have enabled Enhanced Programmable SIP Features on your Twilio.

Back to attributes list

The timeLimit attribute sets the maximum duration of the <Dial> in seconds.

For example, by setting a time limit of 120 seconds, <Dial> will automatically hang up on the called party two minutes into the phone call.

The default time limit on calls is 4 hours — this is also the maximum duration of a call, unless you enable the "24-Hour Maximum Call Duration" feature in your Programmable Voice General Settings, in which case the maximum duration will be 24 hours.

Back to attributes list

Specifying a timeout will set the limit in seconds that <Dial> will wait for the dialed party to answer the call. This tells Twilio how long to let the call ring before giving up and setting no-answer as the DialCallStatus.

timeout's default value is 30 seconds, the minimum allowed value is five seconds, and the maximum value is 600 seconds.

Back to attributes list

Setting the trim attribute to trim-silence will trim leading and trailing silence from your audio files.

Trimming a file may cause the duration of the recording to be slightly less than the duration of the call. The trim attribute defaults to do-not-trim.

Back to attributes list

The Reason for the outgoing call. Use it to specify the purpose of the call that is presented on the called party's phone. (Branded Calls Private Beta)

For more information, visit the Branded Calls page.

Back to attributes list

You may always choose to nest plain text (a string representing a valid phone number) in <Dial> to tell Twilio a phone number to call:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial>415-123-4567</Dial>
4
</Response>

You may also choose to nest nouns within your <Dial> to create connections to other types of devices, conference calls, and call queues.

The noun of a TwiML verb describes the phone numbers, endpoints, and API resources you want to take action on. TwiML nouns are whatever the verb (<Dial>, in this case) acts upon.

The following are the nouns that you can use with <Dial>. Each is a nested XML element:

Nest one of these nouns inside a <Dial> verb like so:

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
const dial = response.dial();
6
dial.number('415-123-4567');
7

8
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial>
4
        <Number>415-123-4567</Number>
5
    </Dial>
6
</Response>

Functionally, the example above behaves exactly like our basic example where we nest a plain-text phone number in our <Dial>. Let's take this TwiML noun nesting one step further.

In the following example, we'll specify that we want a dual-channel recording for a <Dial> with a nested <Conference>.

This code will forward the active caller into a conference called myteamroom. A dual-channel recording of the call will begin when the ringing begins. After the call ends and the recording is ready, Twilio will send recording information back to example.com:

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
const dial = response.dial({
6
    record: 'record-from-ringing-dual',
7
    recordingStatusCallback: 'www.myexample.com'
8
});
9
dial.conference('myteamroom');
10

11
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Dial record="record-from-ringing-dual" 
4
          recordingStatusCallback="www.myexample.com">
5
        <Conference>myteamroom</Conference>
6
    </Dial>
7
</Response>

Twimlets are URLs hosted by Twilio that provide small bits of commonly-used functionality.

• The Forward twimlet will forward all calls to a Twilio number on to another number of your choosing.
• The Simulring twimlet will ring multiple numbers at the same time, and connect the caller to the first person that picks up.
• To dial numbers in turn until one picks up, use the Find Me twimlet.