TwiML™ Voice: <Dial> - Twilio
Register for SIGNAL by 8/31 for $250 off. Register now.

TwiML™ Voice: <Dial>

During an active call, you can use TwiML's <Dial> verb to connect the current caller to another party.

The following example shows the most basic use of <Dial>:

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

If the party at 415-123-4567 answers the call, the two parties can communicate until one hangs up.

The <Dial> verb will end the new call if:

  • the called party does not pick up
  • Twilio receives a busy signal
  • the number does not exist

<Dial> cannot initiate a call directly from Twilio – it will only dial a new party from an active, ongoing call. To start a new outbound call from Twilio, you must make an API request to the Call endpoint.

 

For a step-by-step guide on making your first outbound call with Twilio, try one of our quickstarts that show how to make a call using the Twilio helper libraries.

Twilio will make a GET or POST request to the action URL (if provided) when the <Dial> call ends. Call flow will then continue, using the TwiML you send in response to that request.

If you do not provide an action URL in your <Dial> and the original caller is still on the line, Twilio will continue to render the original TwiML document.

Loading Code Samples...
Language
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.dial('415-123-4567');
response.say('Goodbye');

console.log(response.toString());
using Twilio.TwiML;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Dial("415-123-4567");
        response.Say("Goodbye");

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$response->dial('415-123-4567');
$response->say('Goodbye');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.dial(number: '415-123-4567')
response.say(message: 'Goodbye')

puts response
from twilio.twiml.voice_response import Dial, VoiceResponse, Say

response = VoiceResponse()
response.dial('415-123-4567')
response.say('Goodbye')

print(response)
import com.twilio.twiml.voice.Dial;
import com.twilio.twiml.voice.Number;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Say;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Number number = new Number.Builder("415-123-4567").build();
        Dial dial = new Dial.Builder().number(number).build();
        Say say = new Say.Builder("Goodbye").build();
        VoiceResponse response = new VoiceResponse.Builder().dial(dial)
            .say(say).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>415-123-4567</Dial>
    <Say>Goodbye</Say>
</Response>
Simple dial

With this code, Twilio will connect the original call with a new party by dialing 415-123-4567. Several things might happen next:

  • If someone answers, Twilio connects the caller with the called party.
  • If the initial caller hangs up, the Twilio session ends and the <Say> does not execute.
  • If the line is busy, if there is no answer, or if the called party hangs up, <Dial> exits and the initial caller hears the <Say> text ("Goodbye") before the call flow ends.

<Dial> Attributes

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

Attribute Allowed Values Default Value
action Relative or absolute URL None
answerOnBridge true, false false
callerId A valid phone number, or client identifier if you are dialing a <Client>. Caller's callerId
hangupOnStar true, false false
method GET, POST POST
record do-not-record, record-from-answer, record-from-ringing, record-from-answer-dual, record-from-ringing-dual.

For backward compatibility, true is an alias for record-from-answer and false is an alias for do-not-record.

do-not-record
recordingStatusCallback Relative or absolute URL None
recordingStatusCallbackMethod GET, POST POST. This attribute indicates which HTTP method Twilio should use use when requesting 'recordingStatusCallback'.
recordingStatusCallbackEvent in-progress, completed, failed completed, failed
ringTone ISO 3166-1 alpha-2 country code Defaults to the carrier's ringtone
timeLimit Positive integer (seconds) 14400 seconds (4 hours)
timeout Positive integer (seconds) 30 seconds
trim trim-silence, do-not-trim do-not-trim

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 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:

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, or if a Child call is redirected to a new TwiML URL before being disconnected.
RecordingUrl The URL of the recorded audio. This parameter is included only if record is set on <Dial> and does not include recordings initiated in other ways. The recording file may not yet be accessible when the action callback is sent. Use recordingStatusCallback for reliable notification on when the recording is available for access.

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 specify an action URL for <Dial>, Twilio will continue the initial call after the dialed party hangs up.

Any TwiML verbs included after this <Dial> will be unreachable, as your response to Twilio takes full control of the initial call. If you want to take more actions on that initial call, you must respond to Twilio's request with TwiML instructions on how to handle the call.

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 next verb, Twilio will end the phone call. Note that this is different from the behavior of <Record> and <Gather>.

Back to attributes list

DialCallStatus

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

Possible DialCallStatus values are:

Value Description
completed The called party answered the call and was connected to the caller.
answered When calling a conference, 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.

Back to attributes list

answerOnBridge

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

callerId

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.

By 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:

If you are dialing 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 that client, you could set the callerId attribute to client:joey.

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

In the following example, we use <Dial> to call a phone number from a Twilio Client device:

Loading Code Samples...
Language
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
const dial = response.dial({
  callerId: '+15551112222',
});
dial.number('+15558675310');

console.log(response.toString());
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial(callerId: "+15551112222");
        dial.Number("+15558675310");
        response.Append(dial);

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$dial = $response->dial(['callerId' => '+15551112222']);
$dial->number('+15558675310');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.dial(caller_id: '+15551112222') do |dial|
  dial.number('+15558675310')
end

puts response
from twilio.twiml.voice_response import Dial, Number, VoiceResponse

response = VoiceResponse()
dial = Dial(caller_id='+15551112222')
dial.number('+15558675310')
response.append(dial)

print(response)
import com.twilio.twiml.voice.Dial;
import com.twilio.twiml.voice.Number;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Number number = new Number.Builder("+15558675310").build();
        Dial dial = new Dial.Builder().callerId("+15551112222").number(number)
            .build();
        VoiceResponse response = new VoiceResponse.Builder().dial(dial).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial callerId="+15551112222">
        <Number>+15558675310</Number>
    </Dial>
</Response>
Because this call is <Dial>ing from a Twilio Client connection, we have to explicitly set a valid phone number as our callerId.
Dial a phone number from a Twilio Client

Because this call is <Dial>ing from a Twilio Client connection, we have to explicitly set a valid phone number as our callerId.

Back to attributes list

hangupOnStar

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 of completed to that URL and processes the response.

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

Back to attributes list

method

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:

Loading Code Samples...
Language
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

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

console.log(response.toString());
using Twilio.TwiML;
using Twilio.Http;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Dial("415-123-4567", action: new Uri("/handleDialCallStatus"),
            method: HttpMethod.Get);
        response.Say("I am unreachable");

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$response->dial('415-123-4567', ['action' => '/handleDialCallStatus',
    'method' => 'GET']);
$response->say('I am unreachable');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.dial(action: '/handleDialCallStatus', method: 'GET',
              number: '415-123-4567')
response.say(message: 'I am unreachable')

puts response
from twilio.twiml.voice_response import Dial, VoiceResponse, Say

response = VoiceResponse()
response.dial('415-123-4567', action='/handleDialCallStatus', method='GET')
response.say('I am unreachable')

print(response)
import com.twilio.twiml.voice.Dial;
import com.twilio.twiml.voice.Number;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Say;
import com.twilio.twiml.TwiMLException;
import com.twilio.http.HttpMethod;

public class Example {
    public static void main(String[] args) {
        Number number = new Number.Builder("415-123-4567").build();
        Dial dial = new Dial.Builder().action("/handleDialCallStatus")
            .method(HttpMethod.GET).number(number).build();
        Say say = new Say.Builder("I am unreachable").build();
        VoiceResponse response = new VoiceResponse.Builder().dial(dial)
            .say(say).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<!-- page located at http://example.com/dial_callstatus.xml -->
<Response>
    <Dial action="/handleDialCallStatus" method="GET">
        415-123-4567
    </Dial>
    <Say>I am unreachable</Say>
</Response>
Specify an action URL and method

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.

In this example, the <Say> verb will never execute, as the code at /handleDialCallStatus takes full control of the call.

Back to attributes list

record

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

recordingStatusCallback

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:

Parameter Description
AccountSid The unique identifier of the Account responsible for this recording.
CallSid A unique identifier for the call associated with the recording. This will always refer to the parent leg of a two-leg call.
RecordingSid The unique identifier for the recording.
RecordingUrl The URL of the recorded audio.
RecordingStatus The status of the recording. Possible values are: in-progress, completed, failed.
RecordingDuration The length of the recording, in seconds.
RecordingChannels The number of channels in the final recording file as an integer. Possible values are 1, 2.
RecordingSource The type of call that created this recording. For recordings initiated when record is set on <Dial>, DialVerb is returned.

Back to attributes list

recordingStatusCallbackEvent

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
  • failed: the recording is not available due to a failure

To specify more than one value, separate each with a space.

Default values are: completed and failed.

If you specify any value(s) in <Dial>, the defaults are no longer applicable. 

To pause, resume, or stop recordings, use the recordingStatusCallbackEvent with the Call Recording Controls API.

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.

Loading Code Samples...
Language
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
const dial = response.dial({
  record: 'record-from-ringing-dual',
  recordingStatusCallback: 'www.myexample.com',
});
dial.number('+15558675310');

console.log(response.toString());
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial(record: "record-from-ringing-dual",
            recordingStatusCallback: new Uri("www.myexample.com"));
        dial.Number("+15558675310");
        response.Append(dial);

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$dial = $response->dial(['record' => 'record-from-ringing-dual',
    'recordingStatusCallback' => 'www.myexample.com']);
$dial->number('+15558675310');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.dial(record: 'record-from-ringing-dual',
              recording_status_callback: 'www.myexample.com') do |dial|
  dial.number('+15558675310')
end

puts response
from twilio.twiml.voice_response import Dial, Number, VoiceResponse

response = VoiceResponse()
dial = Dial(
    record='record-from-ringing-dual',
    recording_status_callback='www.myexample.com'
)
dial.number('+15558675310')
response.append(dial)

print(response)
import com.twilio.twiml.voice.Dial;
import com.twilio.twiml.voice.Number;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;

public class Example {
    public static void main(String[] args) {
        Number number = new Number.Builder("+15558675310").build();
        Dial dial = new Dial.Builder().record(Dial.Record
            .RECORD_FROM_RINGING_DUAL)
            .recordingStatusCallback("www.myexample.com").number(number)
            .build();
        VoiceResponse response = new VoiceResponse.Builder().dial(dial).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial record="record-from-ringing-dual"
          recordingStatusCallback="www.myexample.com">
        <Number>+15558675310</Number>
    </Dial>
</Response>
Set Dual-Channel Recording on <Dial>

Back to attributes list

ringTone

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: ringTone will never be applied to calls to <Sip> endpoints.

Back to attributes list

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 automatically hang up on the called party two minutes into the phone call.

The default time limit on calls is four hours – this is also the maximum length of a call.

Back to attributes list

timeout

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 5 seconds, and the maximum value is 600 seconds. 

<Client> calls have a maximum timeout of 60 seconds.

Twilio always adds a 5-second timeout buffer to your <Dial>, so if you enter a timeout value of 10 seconds, you will see an actual timeout closer to 15 seconds.

Back to attributes list

trim

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

<Dial> Nouns

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:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>415-123-4567</Dial>
</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 thise case) acts upon.

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

Noun Description
<Client>

Describes a Twilio Client connection.

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

Read the detailed <Client> documentation for detailed information and usage.

 <Conference>

Describes a conference allowing two or more parties to talk. Connects the active party to a conference call.

See the detailed <Conference> documentation for a walkthrough of how to use Twilio's conferencing functionality.

<Number>

Describes a phone number with more complex attributes. 

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

Read the detailed <Number> documentation for more information and usage.

<Sim>

Describes a Programmable Wireless SIM connection.

See the detailed <Sim> documentation for more information.

<Sip>

Describes a SIP connection.

See the detailed <Sip> documentation for more information.

<Queue>

Identifies a queue that this call should connect to. Allows you to connect the current call to the call waiting at the front of a particular queue. 

Read the <Queue> documentation for a detailed walkthrough of how to use Twilio's queueing functionality.

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

Loading Code Samples...
Language
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

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

console.log(response.toString());
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();

        dial.Number("415-123-4567");
        response.Append(dial);

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$dial = $response->dial();
$dial->number('415-123-4567');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.dial do |dial|
    dial.number('415-123-4567')
end

puts response
from twilio.twiml.voice_response import Dial, Number, VoiceResponse

response = VoiceResponse()
dial = Dial()
dial.number('415-123-4567')
response.append(dial)

print(response)
import com.twilio.twiml.voice.Dial;
import com.twilio.twiml.voice.Number;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Number number = new Number.Builder("415-123-4567").build();
        Dial dial = new Dial.Builder().number(number).build();
        VoiceResponse response = new VoiceResponse.Builder().dial(dial).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Number>415-123-4567</Number>
    </Dial>
</Response>
Use a nested <Number> with Dial

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:

Loading Code Samples...
Language
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
const dial = response.dial({
    record: 'record-from-ringing-dual',
    recordingStatusCallback: 'www.myexample.com'
});
dial.conference('myteamroom');

console.log(response.toString());
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial(record: "record-from-ringing-dual",
            recordingStatusCallback: new Uri("www.myexample.com"));
        dial.Conference("myteamroom");
        response.Append(dial);

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$dial = $response->dial(['record' => 'record-from-ringing-dual',
    'recordingStatusCallback' => 'www.myexample.com']);
$dial->conference('myteamroom');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.dial(record: 'record-from-ringing-dual',
    recording_status_callback: 'www.myexample.com') do |dial|
        dial.conference('myteamroom')
    end

puts response
from twilio.twiml.voice_response import Conference, Dial, VoiceResponse

response = VoiceResponse()
dial = Dial(
    record='record-from-ringing-dual',
    recording_status_callback='www.myexample.com')
dial.conference('myteamroom')
response.append(dial)

print(response)
import com.twilio.twiml.voice.Conference;
import com.twilio.twiml.voice.Dial;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;

public class Example {
    public static void main(String[] args) {
        Conference conference = new Conference.Builder("myteamroom").build();
        Dial dial = new Dial.Builder().record(Dial.Record
            .RECORD_FROM_RINGING_DUAL)
            .recordingStatusCallback("www.myexample.com")
            .conference(conference).build();
        VoiceResponse response = new VoiceResponse.Builder().dial(dial).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial record="record-from-ringing-dual" 
          recordingStatusCallback="www.myexample.com">
        <Conference>myteamroom</Conference>
    </Dial>
</Response>
Set Dual-Channel Recording on <Dial> with nested <Conference>

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

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

Loading Code Samples...
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.dial('415-123-4567');
response.say('Goodbye');

console.log(response.toString());
using Twilio.TwiML;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Dial("415-123-4567");
        response.Say("Goodbye");

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$response->dial('415-123-4567');
$response->say('Goodbye');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.dial(number: '415-123-4567')
response.say(message: 'Goodbye')

puts response
from twilio.twiml.voice_response import Dial, VoiceResponse, Say

response = VoiceResponse()
response.dial('415-123-4567')
response.say('Goodbye')

print(response)
import com.twilio.twiml.voice.Dial;
import com.twilio.twiml.voice.Number;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Say;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Number number = new Number.Builder("415-123-4567").build();
        Dial dial = new Dial.Builder().number(number).build();
        Say say = new Say.Builder("Goodbye").build();
        VoiceResponse response = new VoiceResponse.Builder().dial(dial)
            .say(say).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>415-123-4567</Dial>
    <Say>Goodbye</Say>
</Response>
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
const dial = response.dial({
  callerId: '+15551112222',
});
dial.number('+15558675310');

console.log(response.toString());
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial(callerId: "+15551112222");
        dial.Number("+15558675310");
        response.Append(dial);

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$dial = $response->dial(['callerId' => '+15551112222']);
$dial->number('+15558675310');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.dial(caller_id: '+15551112222') do |dial|
  dial.number('+15558675310')
end

puts response
from twilio.twiml.voice_response import Dial, Number, VoiceResponse

response = VoiceResponse()
dial = Dial(caller_id='+15551112222')
dial.number('+15558675310')
response.append(dial)

print(response)
import com.twilio.twiml.voice.Dial;
import com.twilio.twiml.voice.Number;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Number number = new Number.Builder("+15558675310").build();
        Dial dial = new Dial.Builder().callerId("+15551112222").number(number)
            .build();
        VoiceResponse response = new VoiceResponse.Builder().dial(dial).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial callerId="+15551112222">
        <Number>+15558675310</Number>
    </Dial>
</Response>
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

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

console.log(response.toString());
using Twilio.TwiML;
using Twilio.Http;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Dial("415-123-4567", action: new Uri("/handleDialCallStatus"),
            method: HttpMethod.Get);
        response.Say("I am unreachable");

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$response->dial('415-123-4567', ['action' => '/handleDialCallStatus',
    'method' => 'GET']);
$response->say('I am unreachable');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.dial(action: '/handleDialCallStatus', method: 'GET',
              number: '415-123-4567')
response.say(message: 'I am unreachable')

puts response
from twilio.twiml.voice_response import Dial, VoiceResponse, Say

response = VoiceResponse()
response.dial('415-123-4567', action='/handleDialCallStatus', method='GET')
response.say('I am unreachable')

print(response)
import com.twilio.twiml.voice.Dial;
import com.twilio.twiml.voice.Number;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.voice.Say;
import com.twilio.twiml.TwiMLException;
import com.twilio.http.HttpMethod;

public class Example {
    public static void main(String[] args) {
        Number number = new Number.Builder("415-123-4567").build();
        Dial dial = new Dial.Builder().action("/handleDialCallStatus")
            .method(HttpMethod.GET).number(number).build();
        Say say = new Say.Builder("I am unreachable").build();
        VoiceResponse response = new VoiceResponse.Builder().dial(dial)
            .say(say).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<!-- page located at http://example.com/dial_callstatus.xml -->
<Response>
    <Dial action="/handleDialCallStatus" method="GET">
        415-123-4567
    </Dial>
    <Say>I am unreachable</Say>
</Response>
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
const dial = response.dial({
  record: 'record-from-ringing-dual',
  recordingStatusCallback: 'www.myexample.com',
});
dial.number('+15558675310');

console.log(response.toString());
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial(record: "record-from-ringing-dual",
            recordingStatusCallback: new Uri("www.myexample.com"));
        dial.Number("+15558675310");
        response.Append(dial);

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$dial = $response->dial(['record' => 'record-from-ringing-dual',
    'recordingStatusCallback' => 'www.myexample.com']);
$dial->number('+15558675310');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.dial(record: 'record-from-ringing-dual',
              recording_status_callback: 'www.myexample.com') do |dial|
  dial.number('+15558675310')
end

puts response
from twilio.twiml.voice_response import Dial, Number, VoiceResponse

response = VoiceResponse()
dial = Dial(
    record='record-from-ringing-dual',
    recording_status_callback='www.myexample.com'
)
dial.number('+15558675310')
response.append(dial)

print(response)
import com.twilio.twiml.voice.Dial;
import com.twilio.twiml.voice.Number;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;

public class Example {
    public static void main(String[] args) {
        Number number = new Number.Builder("+15558675310").build();
        Dial dial = new Dial.Builder().record(Dial.Record
            .RECORD_FROM_RINGING_DUAL)
            .recordingStatusCallback("www.myexample.com").number(number)
            .build();
        VoiceResponse response = new VoiceResponse.Builder().dial(dial).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial record="record-from-ringing-dual"
          recordingStatusCallback="www.myexample.com">
        <Number>+15558675310</Number>
    </Dial>
</Response>
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

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

console.log(response.toString());
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();

        dial.Number("415-123-4567");
        response.Append(dial);

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$dial = $response->dial();
$dial->number('415-123-4567');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.dial do |dial|
    dial.number('415-123-4567')
end

puts response
from twilio.twiml.voice_response import Dial, Number, VoiceResponse

response = VoiceResponse()
dial = Dial()
dial.number('415-123-4567')
response.append(dial)

print(response)
import com.twilio.twiml.voice.Dial;
import com.twilio.twiml.voice.Number;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Number number = new Number.Builder("415-123-4567").build();
        Dial dial = new Dial.Builder().number(number).build();
        VoiceResponse response = new VoiceResponse.Builder().dial(dial).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Number>415-123-4567</Number>
    </Dial>
</Response>
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • TwiML
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
const dial = response.dial({
    record: 'record-from-ringing-dual',
    recordingStatusCallback: 'www.myexample.com'
});
dial.conference('myteamroom');

console.log(response.toString());
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial(record: "record-from-ringing-dual",
            recordingStatusCallback: new Uri("www.myexample.com"));
        dial.Conference("myteamroom");
        response.Append(dial);

        Console.WriteLine(response.ToString());;
    }
}
<?php
require_once './vendor/autoload.php';
use Twilio\TwiML;

$response = new TwiML();
$dial = $response->dial(['record' => 'record-from-ringing-dual',
    'recordingStatusCallback' => 'www.myexample.com']);
$dial->conference('myteamroom');

echo $response;
require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.dial(record: 'record-from-ringing-dual',
    recording_status_callback: 'www.myexample.com') do |dial|
        dial.conference('myteamroom')
    end

puts response
from twilio.twiml.voice_response import Conference, Dial, VoiceResponse

response = VoiceResponse()
dial = Dial(
    record='record-from-ringing-dual',
    recording_status_callback='www.myexample.com')
dial.conference('myteamroom')
response.append(dial)

print(response)
import com.twilio.twiml.voice.Conference;
import com.twilio.twiml.voice.Dial;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;

public class Example {
    public static void main(String[] args) {
        Conference conference = new Conference.Builder("myteamroom").build();
        Dial dial = new Dial.Builder().record(Dial.Record
            .RECORD_FROM_RINGING_DUAL)
            .recordingStatusCallback("www.myexample.com")
            .conference(conference).build();
        VoiceResponse response = new VoiceResponse.Builder().dial(dial).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial record="record-from-ringing-dual" 
          recordingStatusCallback="www.myexample.com">
        <Conference>myteamroom</Conference>
    </Dial>
</Response>