Voice

Dial

View as Markdown

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.
<Verto>A Verto client.
<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

action
string

The 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
booleanDefaults to false

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

callerId
string

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

callerName
string

The caller name displayed for Sip calls. This should be an alphanumeric string. Limit is 70 characters.

hangupOnStar
booleanDefaults to false

The initiator of the call can hangup on the dialed number by using the * key.

method
stringDefaults to POST

The method attribute specifies whether the request to action is a GET or a POST. Valid values are GET or POST.

record
stringDefaults to do-not-record

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

recordingStatusCallback
string

The recordingStatusCallback attribute takes in an absolute or relative URL. SignalWire will make a GET or POST request to this URL when recording is available. See below for request parameters.

recordingStatusCallbackEvent
stringDefaults to completed

The different recording statuses. Possible values are completed, in-progress, and absent. To specify multiple events, separate with a space.

recordingStatusCallbackMethod
stringDefaults to POST

Whether the request to recordingStatusCallback URL is a GET or a POST.

recordingStorageUrl
string

The 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
stringDefaults to POST

Specifies which HTTP verb to use when sending the recording to the recordingStorageUrl. Available values are: POST and PUT.

recordingTrack
stringDefaults to both

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

ringTone
string

The 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
integerDefaults to 14400

Maximum duration, in seconds, for a <Dial>. Default value is 4 hours (14400 seconds).

timeout
integerDefaults to 30

The time, in seconds, that SignalWire will wait for a call to be answered before setting the status of the call to no-answer. 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
stringDefaults to do-not-trim

Whether silence in the beginning and end of recordings is removed. Use trim-silence to achieve this behavior.

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:

DialCallDuration
integer

The duration, in seconds, of the dialed call.

DialCallSid
string

The unique identifier of the new call leg.

DialCallStatus
string

The status of the dialed call attempt. See below for status values.

RecordingUrl
string

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

ValueDescription
completedThe number that was dialed answered the call and was successfully connected to the caller.
answeredWhen calling to a conference, the number that was dialed answered the call and was successfully connected to the caller.
busySignalWire received a busy signal when connecting to the dialed number.
no-answerThe number that was dialed did not answer the call in time.
failedSignalWire was unable to connect to the dialed number. This usually occurs when the dialed number does not exist.
canceledThe 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

Payload
1{
2  "AccountSid": "b3877c40-da60-4998-90ad-b792e98472af",
3  "CallSid": "b3877c40-da60-4998-90ad-b792e98472ca",
4  "RecordingSid": "b3877c40-da60-4998-90ad-b792e984re01",
5  "RecordingUrl": "https://example.signalwire.com/api/laml/2010-04-01/Accounts/b3877c40-da60-4998-90ad-b792e98472af/Recordings/b3877c40-da60-4998-90ad-b792e984re01",
6  "RecordingStatus": "completed",
7  "RecordingDuration": 94,
8  "RecordingChannels": 1,
9  "RecordingSource": "RecordVerb"
10}

Examples

A simple dial

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

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

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

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

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Dial record="record-from-ringing"
4          recordingStatusCallback="https://example.com/recording_status">
5        <Number>+10123456789</Number>
6    </Dial>
7</Response>

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

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Dial record="record-from-ringing-dual"
4          recordingStatusCallback="https://example.com/recording_status">
5        <Conference>teamcall</Conference>
6    </Dial>
7</Response>

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.