Vobiz Logo
Vobiz
|API Documentation
Console

The Dial Element

You can use the Dial element to dial one or multiple phone numbers and connect them to the current caller. If the call is picked up, then the caller and receiver will be connected and can communicate until either party hangs up. If the call is not answered, or a busy signal is received, or the phone number dialed doesn't exist, the Dial element will end.

Upon completion of the call, Vobiz makes a GET or POST request to the action URL if one is provided. Based on the value of the Redirect element, the call flow will continue using the XML received from the action URL.

Note: A Number or User element must be present and nested inside Dial for the Dial element to work.

Nesting rules

  • You must nest a Number or User element within the Dial element.
  • Specify a single Number or User value to dial a single number or a SIP user.
  • Specify multiple Number and User elements for simultaneous dialing.

Attributes

AttributeDescription
action
string
Callback-retry configurable

Redirect to this URL after leaving Dial. See the table "Parameters sent to action URL" below for more information.

Allowed values: a fully qualified URL

method
string

Method used to send HTTP request to the action URL.

Allowed values: GET, POST

Defaults to POST.

hangupOnStar
boolean

The caller can press the * key to hang up on the called party but can continue with other operations depending on the application's response.

Allowed values: true, false

Defaults to false.

timeLimit
integer

Used to preset the duration (in seconds) of the call.

Allowed values: positive integer

Defaults to 14,400 seconds (4 hours).

Note: If timeLimit is ≥86,400 seconds, calls will be disconnected after 24 hours.

timeout
integer

The amount of time (in seconds) that the called party has to answer the call (pick up the phone or tap the answer button on a smart phone or SIP phone).

Allowed values: positive integer

No default value.

callerId
string

If set to a string, caller number will be set to this string value.

Allowed values: valid phone number

Defaults to the current caller's callerId.

callerName
string

If set to a string, caller name will be set to this string value.

Allowed values: Any string, maximum of 50 characters

Defaults to caller's callerName.

confirmSound
string
Callback-retry configurable

A remote URL fetched with a POST HTTP request that must return an XML response with Play, Wait, and/or Speak elements only (all others are ignored). The sound indicated by the XML is played to the called party when the call is answered.

Note: This parameter must be specified for confirmKey to work.

Allowed values: a fully qualified URL

confirmTimeout
string

Timeout starts after the call is answered. Entertained only if confirmSound parameter is passed without confirmKey

Note: confirmTimeout value should be greater than duration of confirmSound to auto answer the call once confirmSound is completely played.

Defaults to: 120

confirmKey
string

The digit to be pressed by the called party to accept the call. Used in conjunction with confirmSound.

Allowed values: any digit, #, *

dialMusic
string
Callback-retry configurable

Music to be played to the caller while the call is being connected. This is a remote URL fetched with a POST HTTP request. It must return an XML response with Play, Wait, and/or Speak elements only (all others are ignored). The sound indicated by the XML is played to the caller while the call is being connected.

Setting dialMusic to real plays the real ringtone of the called party. This is also the default behavior if dialMusic is not specified.

Allowed values: a fully qualified URL or real

callbackUrl
string
Callback-retry configurable

URL to be notified when one of these events occur:

  • called party answers the call
  • called party is connected with caller
  • called party hangs up
  • caller presses any digit. See the "Parameters sent to callbackUrl" table below for more information.

Allowed values: a fully qualified URL

Configuring confirmSound and confirmKey invokes the callbackUrl after the called party answers the call and before the called party confirms the call.

callbackMethod
string

Method used to notify callbackUrl.

Allowed values: GET, POST

Defaults to POST.

redirect
boolean

If set to false, don't redirect to action URL.

We expect an XML response from the action URL if this parameter is set to true. The call will be controlled based on the XML returned from the action URL.

Allowed values: true, false

Defaults to true.

digitsMatch
string

A list of digits that are sent to the callbackUrl when the digits pressed by the user match the digitsMatch parameter (A leg).

Allowed values: list of digit patterns separated by a comma. Example: digitsMatch="123,456,789"

digitsMatchBLeg
string

A list of digits that are sent to the callbackUrl when the digits pressed by the user match the digitsMatchBLeg parameter (B leg).

Allowed values: list of digit patterns separated by a comma. Example: digitsMatchBLeg="123,456,789"

sipHeaders
string

SIP headers are always prefixed with X-PH-.

For every HTTP request called by the dialed leg, the SIP headers will be present. Only [A-Z], [a-z], and [0-9] characters are allowed for SIP header key names and values, so that you can URL-encode the values.

Allowed values: list of SIP headers to send, separated by commas. Sent as key=value pair. For example, head1=val1,head2=val2,…,headN=valN.

Parameters sent to action URL

These parameters are sent to the action URL after Dial is completed.

ParameterDescription
DialRingStatus

Indicates whether the Dial attempt rang.

Allowed values: true, false

DialHangupCauseThe standard telephony hangup cause.
DialStatus

Status of the dial.

Allowed values: completed, busy, failed, cancel, timeout, no-answer

DialALegUUIDCallUUID of A leg.
DialBLegUUIDCallUUID of B leg. Empty if nobody answers.

Parameters sent to callbackUrl

These parameters are sent to the callbackUrl, if specified.

ParameterDescription
DialAction

Allowed values: answer, connected, hangup, digits

DialBLegStatus

Indicates whether B leg answered or hung up.

Allowed values: answer, connected, hangup

DialALegUUIDCallUUID of A leg.
DialBLegUUIDCallUUID of B leg. Empty if nobody answers.
DialDigitsMatch

The digits pressed by A leg and matching one digits combination set in digitsMatch attribute.

Only available when DialAction is set to digits.

DialDigitsPressedByReturns the leg of the call on which the digits were pressed — ALeg or BLeg.
DialBLegDuration

Dial duration in seconds from B leg. Only available when DialAction is set to hangup.

DialBLegBillDuration

Dial duration in seconds billed from B leg. Only available when DialAction is set to hangup.

DialBLegFrom

Dial caller number or SIP endpoint for B leg. Only available when DialAction is set to answer, connected, digits, or hangup.

DialBLegTo

Dial called number or SIP endpoint for B leg. Only available when DialAction is set to answer, connected, digits, or hangup.

DialBLegHangupCauseName

The reason for the B leg's hangup. Refer to our list of hangup causes and sources.

DialBLegHangupCauseCode

A unique integer code for the hangup cause. Refer to our list of hangup causes and sources.

DialBLegHangupSource

The entity that triggered the call hangup. Possible hangup sources are: Caller, Callee, Vobiz, API Request, Answer XML, Error, and Unknown

Refer to our list of hangup causes and sources.

STIRVerification
string

For outbound calls: Gives details about the attestation assigned to the call by Vobiz

For inbound calls: Gives details about the attestation received on the inbound call to your Vobiz phone number.

Possible values:

  • Verified means the call is from a verified caller who has authorized access to the customer's caller ID, and hence should be treated with confidence. Verified is equivalent to attestation level A.
  • Not Verified means that, for this call, either the caller is not verified, or it's uncertain whether they have access to the caller ID used, or both. Not Verified means the call received attestation level B or C.
  • Not Applicable means STIR/SHAKEN doesn't apply to this call, as would be the case if a call is not addressed to a US number or if it's a cloud call (WebRTC or SIP).

Read more about STIR/SHAKEN here.

Conference
DTMF