<Dial>

TL;DR

<Dial> a destination, a conference bridge, a remote SIP endpoint or a service provider.

Need Help? Let's Talk

Join our Discord community - we're here to help.

Description

The <Dial> verb allows an application to dial to a Cloudonix subscriber (both using classic SIP registration as well as Registration-Free subscriber), an external DID through a configured SIP trunk, to a SIP URL, or to other destinations using dedicated Noun elements (such as conferences or queues).

Example

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

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>1-805-101010</Dial>
</Response>

A slightly more advanced usage may include a specific Cloudonix trunk ID selector:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial trunks="outbound-trunk"><Number>1-805-101010</Number></Dial>
</Response>

Unlike most CXML operations, using <Dial> will not cause the Voice Application to answer the call - the call will only be answered if the destination of the <Dial> will pick up the call. Of course that this does not affect the answer status of the current call if it was already answered (for example due to multiple <Dial> operations used in the same application).

Content

The content of the <Dial> element may be any one or more of the "Dial nouns" (as per each dial noun specification, see below) or plain text - in which case the content will be understood to be either a single <Number> dial noun (see the <Number> documentation for details) or - if the content is a SIP URL - as a single <Sip> dial noun (see the <Sip> documentation for details).

Attributes

The following attributes are supported:

Attribute Name	Allowed Values	Default Value
action	Relative or absolute URL	None
callerId	A valid phone number, or client identifier if you are dialing a <Client>.	Caller's callerId
callerName	Any text	Caller's display name
forwardHeaders	Boolean value (true or false)	false
headers	application/x-www-form-urlencoded encoded key/value pairs	None
hangupOnStar	true,false	false
hangupOn	DTMF character	None
method	GET, POST	POST
record	do-not-record, record-from-answer, record-from-ringing	do-not-record
recordingStatusCallback	Relative or absolute URL	None
recordingStatusCallbackMethod	GET, POST	POST
recordingStatusCallbackEvent	in-progress, completed, absent	completed
timeLimit	Positive integer (seconds)	14400
timeout	Positive integer (seconds)	The domain's call-timeout property value, if set, otheriwse 60
trim	do-no-trim, trim-silence	do-not-trim
trunks	Comma or space separated list of trunks or wildcards	None

Attribute: action

The URL to an application stage to be called once the dial operation is completed (i.e. the other side had disconnected, timed out or there was an error). The application will be called with additional request arguments providing details on the result of the dial operation:

• DialCallStatus - the status of the dial operation.
• DialCallSid - the call ID of the new call leg.
• DialCallDuration - the duration in seconds of the dialed call, including the time it to the call to be answered.
• RecordingUrl - the URL where the call recording (if any) can be retrieved from.

Attribute: callerId

The caller identification number to show the receiver of the call.

Attribute: callerName

The caller display name to show the receiver of the call. This is most useful when calling subscribers over SIP, as other protocols are likely to drop the display name.

Attribute: forwardHeaders

If set to true, and custom headers were read from the originator of the call (into the trunk-sip-headers or subscriber-sip-headers session profile properties), the Dial verb will copy all received headers into the custom outgoing SIP headers for the session, as stored in the sip-headers session profile property.

Attribute: headers

If set, the list of key value pairs will be parsed (as per the rules for the application/x-www-form-urlencoded media content type) into a list of custom SIP headers that will be set in the sip-headers session profile property so such headers will be set on the SIP INVITE sent to the callee (in case of registered subscriber or trunk, or as a specific field for a Registration-Free subscriber - see the Registration-Free protocol documentation for details).

If forwardHeaders was also set, any conflicting header set using the headers attribute will override any received header. In addition, if the headers attribute contains a header specification with only a key (the value is an empty string), then the specified SIP header will be unset if a case-insensitive matching header was received from the session originator.

SIP headers specified using the headers attribute are sent to subscribers (either registered or Registration-Free) as specified, but when dialing to a trunk (or direct SIP address) such headers are first prefixed with X-CX-Session-. For a fully custom header name on trunk INVITEs, see the <Header> noun below.

Example:

<Dial headers="FullName=John+Smith&Location=office">19995551234</Dial>

Attribute: hangupOnStar

If set to true, the caller can punch the DTMF signal for "star" (*) to hangup the remote at any point and to have the application execute the action.

Attribute: hangupOn

A more advanced alternative to hangupOnStar - set any DTMF character to hangup the <Dial>. Set hangupOn="*" to emuldate hangupOnStar, or set it to any one other DTMF character to attach the hangup event to the caller sending that DTMF event.

Attribute: method

The HTTP method to use when calling the action URL at the end of the dial operation.

Attribute: record

Whether to record the new call.

Attribute: recordingStatusCallback

The URL to receive a notification when the call recording status has changed, as per the recordingStatusCallbackEvent setting (if record was set to anything other than do-not-record).

When Cloudonix calls this URL, it will pass the following arguments:

• CallSid - the unique call ID associated with the recorded call.
• Session - the session token for the recorded call.
• RecordingSid - the unique identifier for the recording.
• RecordingUrl - a URL where the completed recording may be accessed
• RecordingStatus - status of the recording. Possible values are: in-progress, completed, absent.
• RecordingDuration - the length of the recording, in seconds.
• RecordingStartTime - the timestamp of when the recording started.

Attribute: recordingStatusCallbackMethod

The HTTP method to use when calling the recordingStatusCallback URL.

Attribute: recordingStatusCallbackEvent

When to call the recordingStatusCallback, could be one of:

• in-progress - when the recording has started.
• completed - when the recording has completed and is ready to download.
• absent - when there was an error processing the recording and the recording is not available.

Attribute: timeLimit

Override the maximum time limit on the call, as was set on the session during creation. If set to a value higher than 14400, that value will be ignored.

Attribute: timeout

Override the ringing timeout specified by the domain property call-timeout.

Attribute: trim

When recording the call, whether to trim silence from the beginning and end of the recording. By default, no trimming will be done.

Attribute: trunks

Send the call out through the trunk or trunks specified, overriding a session LCR plan if set. If this value is not set, and the current session has no LCR plan, then the dial operation will be sent to an available subscriber with a matching destination address, or if no matching subscriber is found, and the domain property redirect-unknown-to-border is not set to false - the dial operation will be sent to a trunk as per the default or custom LCR plan.

The trunk attribute accepts a space or comma separated list of trunk identifiers, where a trunk identifier may be:

• The name of the domain's outbound trunk.
• The UUID of the domain's outbound trunk.
• The numeric ID of the domain's outbound trunks.
• A wildcard experssion that matches one or more of the domain's outbound trunks by bame. The bare "catch all" wildcard - "*" - would select all existing outbound trunks sorted by name. This would be useful to force a call to route to a trunk without needing to know which specific trunks are configured.

Dial Nouns

The following Dial "nouns" are supported by Cloudonix:

• <Conference> - Conference Room Functionality.
• <Number> - Dial a Cloudonix subscriber or an external subscriber through a trunk.
• <Sip> - Dial directly to a SIP address.
• <Service> - Dial a 3rd party service provider.
• <Header> - Add a custom SIP Header to <DIAL> operation.