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:

AttributeAllowed ValuesDefault Value
actionrelative or absolute URLno default action for Dial
methodGET, POSTPOST
timeoutpositive integer30 seconds
hangupOnStartrue, falsefalse
timeLimitpositive integer (seconds)14400 seconds (4 hours)
callerIda valid phone number, or client identifier if you are dialing a <Client>.Caller's callerId
recorddo-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
trimtrim-silence, do-not-trimtrim-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:

ParameterDescription
DialCallStatusThe outcome of the <Dial> attempt. See the DialCallStatus section below for details.
DialCallSidThe call sid of the new call leg. This parameter is not sent after dialing a conference.
DialCallDurationThe duration in seconds of the dialed call. This parameter is not sent after dialing a conference.
RecordingUrlThe 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:

ParameterDescription
QueueSidThe SID of the queue.
DequeueResultOne of invalid, bridged, queue-not-found, queue-empty or failed.
DequeuedCallSidThe CallSid of the dequeued call.
DequeuedCallQueueTimeThe time the dequeued call spent waiting in the queue.
DequeuedCallDurationThe time the call was bridged with the dequeued call.
DialCallStatus Values
ValueDescription
completedThe called party answered the call and was connected to the caller.
busyTwilio received a busy signal when trying to connect to the called party.
no-answerThe called party did not pick up before the timeout period passed.
failedTwilio was unable to route to the given phone number. This is frequently caused by dialing a properly formatted but non-existent phone number.
canceledThe 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>:

NounDescription
plain textA 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>