<Dial>

The <Dial> verb connects the current caller to another party.

<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	valid phone number	caller's callerId
hangupOnStar	true, false	false
method	GET, POST	POST
history	disable, compact, full	disable
output	alphanumeric name	none
ringTone	see below	us
timeout	integer > 0	30 seconds
timeLimit	integer > 0	4 hours
record	do-not-record, record-from-ringing, record-from-answer, record-from-ringing-dual, record-from-answer-dual	do-not-record
recordingTrack	inbound, outbound, both	both
recordingStatusCallback	relative or absolute URL	none
recordingStatusCallbackMethod	GET, POST	POST
recordingStatusCallbackEvent	in-progress, completed, failed	completed

action

The action attribute accepts a URL as its argument. The URL tells Voxtelesys where to make a POST or GET request after the dialed call ends.

If you do not provide an action URL, <Dial> will finish and Voxtelesys will move on to the next VoXML verb in the document.

See additional parameters sent on the action webhook.

answerOnBridge

If the call has not yet been answered, answerOnBridge="true" will cause the inbound call to ring until the dialed number answers.

Effectively, Voxtelesys will send a 18x SIP code when the initial call connects to Voxtelesys. Once the <Dial> call connects, Voxtelesys will answer with a 200.

callerId

The callerId attribute allows you to specify the caller ID to display on the <Dial> call. By default this is set to the inbound caller's number.

For example:

1. Someone with a caller ID of 800-800-8000 calls your Voxtelesys number.
2. You tell Voxtelesys to execute a <Dial> verb to 900-900-9000 to handle the inbound call.
3. The called party (900-900-9000) will see 800-800-8000 as the caller ID on the incoming call.

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>, Voxtelesys blocks execution of further verbs until the caller or callee 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 Voxtelesys processing session).

When the caller presses *, Voxtelesys will hang up on the called party. If an action URL was provided, Voxtelesys will fetch and process the VoXML provided by the URL.

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

method

The method attribute accepts either GET or POST. This tells Voxtelesys whether to request the action URL via HTTP GET or POST, with POST as its default value.

record

The record attribute tells Voxtelesys whether to record the dialed call. By default, the value is do-not-record. If a recording is desired, you can specify either mono-channel or dual-channel.

Mono-channel recordings involve combining both the caller and the callee into a single channel in the audio recording file. For mono-channel recordings, the options are:

• record-from-ringing: start the recording as soon as the dialed call rings.
• record-from-answer: start the recording once the dialed callee answers.

Dual-channel recordings, on the other hand, separate the caller's and callee's voices into separate channels in the audio recording file. The options for dual channel are:

record-from-ringing-dual: start the recording as soon as the dialed call rings (dual-channel). record-from-answer-dual: start the recording once the dialed callee answers (dual-channel).

By convention, the caller will be in the right channel and the dialed callee will be in the left channel.

recordingTrack

The recordingTrack attribute specifies which side of the dialed call to record. The options are inbound, outbound, and both, and the default is both. If outbound is specified, then only the voice of the dialed callee will be recorded. If inbound is specified, the only the voice of the dialing caller will be recorded. If inbound or outbound is specified, then the resulting audio recording will always be mono-channel.

recordingStatusCallback

The recordingStatusCallback attribute accepts a relative or absolute URL. If a recordingStatusCallback is given, then an HTTP request will be sent to the specified URL with information for each recording status that is requested in recordingStatusCallbackEvent.

See additional parameters sent on the recordingStatus webhook.

recordingStatusCallbackMethod

The recordingStatusCallbackMethod attribute specifies which HTTP method to use when sending a callback to the recordingStatusCallback URL. The default is POST.

recordingStatusCallbackEvent

The recordingStatusCallbackEvent attribute accepts a list of events for which HTTP callbacks should be sent to recordingStatusCallback. To specify more than one event, separate each event name with a space. The default is completed, and the available events are:

• in-progress: the recording has started.
• completed: the recording has finished and has been uploaded.
• failed: the recording failed to be uploaded and is not available.

history

The history attribute determines if the <Dial> verb should be logged in the history array of the CDR. The default is to not log.

For <Dial>, the compact and full values log the following payload to the history array respectively.

compact

{
  "payload": {
    "numbers": [
      "13003003000"
    ],
    "action": "/next"
  }
}

full

{
  "payload": {
    "numbers": [
      "13003003000"
    ],
    "action": "/next",
    "method": "POST",
    "answerOnBridge": "true",
    "callerId": "14004004000",
    "ringTone": "us",
    "timeout": 30,
    "timeLimit": 120,
    "record": "record-from-answer",
    "recordingTrack": "both",
    "recordingStatusCallblack": "http://example.com",
    "recordingStatusCallbackMethod": "POST",
    "recordingStatusCallbackEvent": "completed"
  }
}

The <Dial> verb will also generate an element in the history array with the final status of <Dial>, if either compact or full is used.

{
  "payload": {
    "status": "completed"
  }
}

output

The output attribute accepts an alphanumeric variable name, up to 50 characters. The final status of <Dial> is saved to this variable via the <output>.status variable.

ringTone

The ringTone attribute allows you to override the ringback tone that Voxtelesys will play back to the caller while executing the <Dial>.

Accepted values are: au, be, cn, cz, de, dk, es, fi, fr, hu, il, in, jp, pl, uk, us.

timeout

The timeout attribute sets the limit in seconds that <Dial> will wait for the dialed party to answer the call. This tells Voxtelesys 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 five seconds, and the maximum value is 600 seconds.

timeLimit

The timeLimit attribute sets the maximum duration of <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.

<Dial> Nouns

You may choose to nest plain text (a string representing a valid phone number) in <Dial> to tell Voxtelesys a phone number to call.

You may also choose to nest up to 10 <Number> nouns within the <Dial> verb.

<Dial> Webhooks

action Webhook

If you specify an action URL, Voxtelesys will send a webhook with the following additional 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 VoXML URL before being disconnected.
RecordingUrl	The URL of the recorded audio file, if applicable.

The possible values for DialCallStatus 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	Voxtelesys 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	Voxtelesys 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.

recordingStatus Webhook

If you specify a recordingStatusCallback URL, Voxtelesys will send a webhook with the following additional parameters:

Parameter	Description
RecordingSid	The unique ID of the recording.
RecordingUrl	The URL of the recorded audio file
RecordingDuration	The duration of the audio recording.
RecordingStatus	The status of the recording. The possible values are in-progress, completed, and failed.
RecordingChannels	The number of channels in the final recording file.
RecordingSource	The method used to create this recording. For <Dial>, this will always be DialVerb.

The possible values for RecordingStatus are:

Value	Description
in-progress	The recording has started.
completed	The recording has finished and has been uploaded.
failed	The recording failed to be uploaded and is not accessible.

<Dial> Examples

Simple Usage

Welcome the caller and transfer them to an agent.

<Response>
  <Say>Hello. Please stay on the line while I transfer you to an agent.</Say>
  <Dial>13003003000</Dial>
</Response>

Advanced Usage

Welcome the caller and transfer them to multiple agents. Kill the call at the 1hr mark.

<Response>
  <Say>Hello. Please stay on the line while I transfer you to an agent.</Say>
  <Dial timeout="30" timeLimit="3600">
    <Number>13003003000</Number>
    <Number>13003003001</Number>
    <Number>13003003002</Number>
  </Dial>
</Response>