<Dial>

The <Dial> verb connects an existing call to another phone number. <Dial> will end this new call if: the called number does not answer, the number does not exist, or SignalWire receives a busy signal.

You can use the <Dial> verb with the following nouns:

Noun
<Conference>A conference call between two or more callers.
<Number>A phone number with additional attributes.
<Sip>A SIP endpoint.
<Queue>A line for callers to wait in. The current call will be connected to the call at the front of the queue.

Verb Attributes

Attribute
action optionalThe action attribute takes in an absolute URL. SignalWire will make a GET or POST request to this URL after the dialed call ends. If no action is provided, SignalWire will continue to the next verb in the document. SignalWire will end the call if there are no more verbs following the <Dial> verb in the document. See below for request parameters.
answerOnBridge optionalIf set to true, the inbound call will ring until the number that was dialed answers the call. If the inbound call is a SIP call, SignalWire will send a 180 or 183 to your SIP server as soon as it connects to SignalWire. When the <Dial> call is connected, a 200 will be sent. Default value is false.
callerId optionalThe inbound caller's phone number, which is displayed to the number that was dialed. The caller ID must be a valid E.164 number. Note that the number specified here must either be verified or purchased in the SignalWire dashboard.
hangupOnStar optionalThe initiator of the call can hangup on the dialed number by using the * key. Default value is false.
method optionalThe method attribute specifies whether the request to action is a GET or a POST. Valid values are GET or POST, default value is POST.
record optionalThe record attribute allows the ability to record both legs of a call. Recordings are available as mono-channel or dual-channel. See below for a detailed explanation of these channels. Default value is do-not-record.
recordingStatusCallback optionalThe recordingStatusCallback attribute takes in an absolute or relative URL. SignalWire will make a GET or POST request to this URL when recording is available. Default value is POST. See below for request parameters.
recordingStatusCallbackEvent optionalThe different recording statuses. Possible values are completed, in-progress, and absent. To specify multiple events, separate with a space. Defaults to completed.
recordingStatusCallbackMethod optionalWhether the request to recordingStatusCallback URL is a GET or a POST. Default is POST.
recordingStorageUrl optionalThe recordingStorageUrl attribute accepts an absolute URL as the destination to send a recording to, if you prefer to host your own recordings and bypass SignalWire storage. The recording files are in .wav format.
recordingStorageUrlMethod optionalSpecifies which HTTP verb to use when sending the recording to the recordingStorageUrl. Available values are: POST and PUT. Defaults to POST.
recordingTrack optionalSpecifies whether to record the inbound audio to SignalWire from the called party or the outbound audio from SignalWire to the called party or both the inbound and outbound audio. Defaults to both.
ringTone optionalThe ability to change the ringback tone played to the caller when dialing a number. Default value is the ringback tone from the carrier. Available values are the following ISO 3166-1 alpha-2 country codes: 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.
timeLimit optionalMaximum duration, in seconds, for a <Dial>. Default value is 4 hours.
timeout optionalThe time, in seconds, that SignalWire will wait for a call to be answered before setting the status of the call to no-answer. Default is 30 seconds. Minimum value is 5 seconds and maximum value is 600 seconds. For some call flows, there may be a 5-second buffer added to the timeout value you provide.
trim optionalWhether silence in the beginning and end of recordings is removed. Use trim-silence to achieve this behavior. Default value is do-not-trim.

Request parameters for the action URL

You can expect several parameters to be present in the request associated to the action URL. First, you have the Standard Request Parameters. Then, you also have the following specific parameters:

Parameter
DialCallStatus stringThe status of the dialed call attempt. See below for status values.
DialCallSid stringThe unique identifier of the new call leg.
DialCallDuration integerThe duration, in seconds, of the dialed call.
RecordingUrl stringThe URL of the recorded audio file. This parameter is only present if record is set on a <Dial>.

Values for DialCallStatus parameter

The DialCallStatus parameter of the action attribute can be one of the following values:

Value
completed The number that was dialed answered the call and was successfully connected to the caller.
answered When calling to a conference, the number that was dialed answered the call and was successfully connected to the caller.
busy SignalWire received a busy signal when connecting to the dialed number.
no-answer The number that was dialed did not answer the call in time.
failed SignalWire was unable to connect to the dialed number. This usually occurs when the dialed number does not exist.
canceled The call was canceled through a REST API before it was answered.

Values for record parameter

The record attribute allows for recordings in mono-channel or dual-channel:

  • mono-channel: both legs of a call are combined into one channel in one recording file
    • record-from-answer: starts the recording when the call is answered
    • record-from-ringing: starts the recording when ringing begins
  • dual-channel: both legs of a call use separate channels in one recording file
    • record-from-answer-dual: starts the recording when the call is answered
    • record-from-ringing-dual: starts the recording when ringing begins

Request parameters for recordingStatusCallback

The recordingStatusCallback request contains the following parameters:

Parameter
AccountSid stringThe unique ID of the Account this call is associated with.
CallSid stringA unique identifier for the call. Always refers to the initial caller.
RecordingSid stringThe unique identifier for the recording.
RecordingUrl stringThe URL for the audio recording.
RecordingStatus stringThe status of the recording. Possible values are: in-progress, completed, failed.
RecordingDuration integerThe duration, in seconds, of the recording.
RecordingChannels integerThe number of channels in the recording. Can be 1 or 2.
RecordingSource stringThe type of call that initiated the recording.
RecordingTrack stringWhich audio tracks are recorded. Can be inbound, outbound, or both.

Examples

A Simple Dial

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>123-456-7890</Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

response.dial('123-456-7890')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $response->dial('123-456-7890');
  echo $response;
?>
using Twilio.TwiML;
using System;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Dial("123-456-7890");

        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Dial

response = VoiceResponse()
response.dial('123-456-7890')

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial('123-456-7890')
end

puts response.to_s

If the dialed number answers the call, the two parties can talk to each other until one of them hangs up the phone.

Dial a Number from a SignalWire Client

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial callerId="+18007778899">
        <Number>+18004445566</Number>
    </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial({ callerId: '+18007778899' })
dial.number('+18004445566')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial(array( 'callerId' => '+18007778899' ));
  $dial->number('+18004445566');
  echo $response;
?>
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


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

        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Dial, Number

response = VoiceResponse()
dial = Dial(caller_id='+18007778899')
dial.number('+18004445566')
response.append(dial)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial(caller_id: '+18007778899') do |dial|
    dial.number('+18004445566')
  end
end

puts response.to_s

In order to dial from a SignalWire client, you need to make sure you are inputting a valid phone number. If the number in the callerID is not valid, the call will fail.

Mono-Channel Recording

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial record="record-from-ringing"
          recordingStatusCallback="https://example.com/recording_status">
        <Number>+10123456789</Number>
    </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial({ record: 'record-from-ringing', recordingStatusCallback: 'https://example.com/recording_status' })
dial.number('+10123456789')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial(array(
    'record' => 'record-from-ringing',
    'recordingStatusCallback' => 'https://example.com/recording_status' )
  );
  $dial->number('+10123456789');
  echo $response;
?>
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",
            recordingStatusCallback: new Uri("https://example.com/recording_status"));
        dial.Number("+10123456789");
        response.Append(dial);

        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Dial, Number

response = VoiceResponse()
dial = Dial(record='record-from-ringing', recording_status_callback='https://example.com/recording_status')
dial.number('+10123456789')
response.append(dial)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial(record: 'record-from-ringing', recording_status_callback: 'https://example.com/recording_status') do |dial|
    dial.number('+10123456789')
  end
end

puts response.to_s

With mono-channel recording, each participant in the call will be recorded on the same channel. The recording will then be stored in a single recording file. Since we have set record to record-from-ringing, the recording will begin when the phone starts to ring.

Dual-Channel Recording for a Conference Call

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial record="record-from-ringing-dual"
          recordingStatusCallback="https://example.com/recording_status">
        <Conference>teamcall</Conference>
    </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial({ record: 'record-from-ringing-dual', recordingStatusCallback: 'https://example.com/recording_status' })
dial.conference('teamcall')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial(array(
    'record' => 'record-from-ringing-dual',
    'recordingStatusCallback' => 'https://example.com/recording_status' )
  );
  $dial->conference('teamcall');
  echo $response;
?>
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("https://example.com/recording_status"));
        dial.Conference("teamcall");
        response.Append(dial);

        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Dial, Conference

response = VoiceResponse()
dial = Dial(record='record-from-ringing-dual', recording_status_callback='https://example.com/recording_status')
dial.conference('teamcall')
response.append(dial)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial(record: 'record-from-ringing-dual', recording_status_callback: 'https://example.com/recording_status') do |dial|
    dial.conference('teamcall')
  end
end

puts response.to_s

This example connects the caller to the conference call, teamcall. With dual-channel recording, each participant in the call will be recorded in a separate channel. The recording will then be stored in a single recording file. Since we have set record to record-from-ringing-dual, the recording will begin when the phone starts to ring.