Get Started

TwiMLTM Voice: <Dial>

The <Dial> verb connects the current caller to another phone. If the called party picks up, the two parties are connected and can communicate until one hangs up. If the called party does not pick up, if a busy signal is received, or if the number doesn't exist, the dial verb will finish.

When the dialed call ends, Twilio makes a GET or POST request to the 'action' URL if provided. Call flow will continue using the TwiML received in response to that request.

Verb Attributes

The <Dial> verb supports the following attributes that modify its behavior:

Attribute Allowed Values Default Value
action relative or absolute URL no default action for Dial
method GET, POST POST
timeout positive integer 30 seconds
hangupOnStar true, false false
timeLimit positive integer (seconds) 14400 seconds (4 hours)
callerId a valid phone number, or client identifier if you are dialing a <Client>. Caller's callerId
record do-not-record, record-from-answer, record-from-ringing. For backward compatibility, 'true' is an alias for 'record-from-answer' and 'false' is an alias for 'do-not-record'. do-not-record
trim trim-silence, do-not-trim trim-silence

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

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

action

The 'action' attribute takes a URL as an argument. When the dialed call ends, Twilio will make a GET or POST request to this URL including the parameters below.

If you provide an 'action' URL, Twilio will continue the current call after the dialed party has hung up, using the TwiML received in your response to the 'action' URL request. Any TwiML verbs occurring after a <Dial> which specifies an 'action' attribute are unreachable.

If no 'action' is provided, <Dial> will finish and Twilio will move on to the next TwiML verb in the document. If there is no next verb, Twilio will end the phone call. Note that this is different from the behavior of <Record> and <Gather>. <Dial> does not make a request to the current document's URL by default if no 'action' URL is provided. Instead the call flow falls through to the next TwiML verb.

Request Parameters

Twilio will pass the following parameters in addition to the standard TwiML Voice request parameters with its request to the 'action' URL:

Parameter Description
DialCallStatus The outcome of the <Dial> attempt. See the DialCallStatus section below for details.
DialCallSid The call sid of the new call leg. This parameter is not sent after dialing a conference.
DialCallDuration The duration in seconds of the dialed call. This parameter is not sent after dialing a conference.
RecordingUrl The URL of the recorded audio. This parameter is only sent if a recording is used with the <Dial> verb, and does not include recordings from the <Record> verb, Record=True on REST API calls, or <Conference> record.

When the <Queue> noun is dialed, the following additional parameters are provided:

Parameter Description
QueueSid The SID of the queue.
DequeueResult One of invalid, bridged, queue-not-found, queue-empty or failed.
DequeuedCallSid The CallSid of the dequeued call.
DequeuedCallQueueTime The time the dequeued call spent waiting in the queue.
DequeuedCallDuration The time the call was bridged with the dequeued call.
DialCallStatus Values
Value Description
completed The called party answered the call and was connected to the caller.
busy Twilio received a busy signal when trying to connect to the called party.
no-answer The called party did not pick up before the timeout period passed.
failed Twilio was unable to route to the given phone number. This is frequently caused by dialing a properly formatted but non-existent phone number.
canceled The call was canceled via the REST API before it was answered.

method

The 'method' attribute takes the value 'GET' or 'POST'. This tells Twilio whether to request the 'action' URL via HTTP GET or POST. This attribute is modeled after the HTML form 'method' attribute. 'POST' is the default value.

timeout

The 'timeout' attribute sets the limit in seconds that <Dial> waits for the called party to answer the call. Basically, how long should Twilio let the call ring before giving up and reporting 'no-answer' as the 'DialCallStatus'.

hangupOnStar

The 'hangupOnStar' attribute lets the calling party hang up on the called party by pressing the '*' key on his phone. When two parties are connected using <Dial>, Twilio blocks execution of further verbs until the caller or called party hangs up. This feature allows the calling party to hang up on the called party without having to hang up her phone and ending her TwiML processing session. When the caller presses '*' Twilio will hang up on the called party. If an 'action' URL was provided, Twilio submits 'completed' as the 'DialCallStatus' to the URL and processes the response. If no 'action' was provided Twilio will continue on to the next verb in the current TwiML document.

timeLimit

The 'timeLimit' attribute sets the maximum duration of the <Dial> in seconds. For example, by setting a time limit of 120 seconds <Dial> will hang up on the called party automatically two minutes into the phone call. By default, there is a four hour time limit set on calls.

callerId

The 'callerId' attribute lets you specify the caller ID that will appear to the called party when Twilio calls. By default, when you put a <Dial> in your TwiML response to Twilio's inbound call request, the caller ID that the dialed party sees is the inbound caller's caller ID.

For example, an inbound caller to your Twilio number has the caller ID 1-415-123-4567. You tell Twilio to execute a <Dial> verb to 1-858-987-6543 to handle the inbound call. The called party (1-858-987-6543) will see 1-415-123-4567 as the caller ID on the incoming call.

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

If you are dialing a phone number from a Twilio Client connection, you must specify a valid phone number as the callerId or the call will fail.

You are allowed to 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

record

The 'record' attribute lets you record both legs of a call within the associated <Dial> verb. When using record-from-answer, the recording will begin when a call is answered. When using record-from-ringing, the recording will begin when the ringing starts. In both cases, a RecordingUrl parameter will be sent to the 'action' URL on the associated <Dial> verb. You must set an 'action' URL to receive the RecordingUrl.

trim

The 'trim' attribute lets you specify whether to trim leading and trailing silence from your audio files. 'trim' defaults to trim-silence, which removes any silence at the beginning or end of your recording. This may cause the duration of the recording to be slightly less than the duration of the call.

Nouns

The "noun" of a TwiML verb is the stuff nested within the verb that's not a verb itself; it's the stuff the verb acts upon. These are the nouns for <Dial>:

Noun Description
plain text A string representing a valid phone number to call.
<Number> A nested XML element that describes a phone number with more complex attributes.
<Client> A nested XML element that describes a Twilio Client connection.
<Sip> A nested XML element that describes a SIP connection.
<Conference> A nested XML element that describes a conference allowing two or more parties to talk.
<Queue> A nested XML element identifying a queue that this call should be connected to.

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

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Number>415-123-4567</Number>
    </Dial>
</Response>

<Number> Noun

The <Number> noun allows you to <Dial> another number while specifying additional behavior pertaining to that number. Simultaneous dialing is also possible using multiple <Number> nouns.

See the documentation on the <Number> noun for a detailed walkthrough of how to use it.

<Client> Noun

The <Client> noun allows you to <Dial> a Twilio Client connection.

Simultaneous dialing is also possible using multiple <Client> nouns.

See the documentation on the <Client> noun for a detailed walkthrough of how to use it.

<Sip> Noun

The <Sip> noun allows you to <Dial> a SIP endpoint.

See the documentation on the <Sip> noun for a detailed walkthrough of how to use it.

<Conference> Noun

The <Conference> noun allows you to <Dial> into a conference room, rather than <Dial> another number. See the documentation on the <Conference> noun for a detailed walkthrough of how to use Twilio's conferencing functionality.

<Queue> Noun

The <Queue> noun allows you to connect the current call to the call waiting at the front of a particular queue. See the documentation on the <Queue> noun for a detailed walkthrough of how to use Twilio's queueing functionality.

See Also

The Calls resource in Twilio's REST API

Using <Dial> With Twimlets

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.

Examples

Example 1: Simple dial

This is the simplest case for Dial. Twilio will dial 415-123-4567. If someone answers, Twilio will connect the caller to the called party. If the caller hangs up, the Twilio session ends. If the line is busy, if there is no answer, or if the called party hangs up, <Dial> exits and the <Say> verb is executed for the caller before the call flow ends.

<?xml version="1.0" encoding="UTF-8"?>
<!-- page located at http://example.com/simple_dial.xml -->
<Response>
    <Dial>415-123-4567</Dial>
    <Say>Goodbye</Say>
</Response>

Example 2: DialCallStatus reporting

In this example provide an action URL and method. Now when <Dial> ends, Twilio will submit a request to the action URL with the parameter 'DialCallStatus'. If nobody picks up, 'DialCallStatus' will be 'no-answer'. If the line is busy, 'DialCallStatus' will be 'busy'. If the called party picks up, 'DialCallStatus' will be 'completed'. If an invalid phone number was provided, 'DialCallStatus' will be 'failed'.

Your web application can look at the 'DialCallStatus' parameter and decide what to do next.

If an 'action' URL is provided for <Dial>, Twilio will always make a request to it regardless of the outcome of <Dial>. All verbs remaining in the document are unreachable and ignored.

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

Example 3: Dial to a phone number from Twilio Client

In this example, we'll use <Dial> to call a phone number from a Twilio Client device.

If you are dialing a phone number from a Twilio Client connection, you must specify a valid phone number as the callerId or the call will fail.
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial callerId="+15551112222">
        <Number>+15558675309</Number>
    </Dial>
</Response>