The Dial Element

The Dial element is used to dial a single or multiple phone numbers and connect them to the current caller. If the call is picked up, then the caller and receiver are connected and can communicate until either party hangs up. If the call is not answered, or a busy signal is received, or if the phone number dialed does not exist, the Dial element will end.

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

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

Nesting Rules

  • The Number element or the User element should be nested within the Dial element.
  • A single Number or User value can be specified to dial a single number or a SIP user.
  • Simultaneous dialing is also possible by using a combination of multiple Number and User elements.

Attributes

action string

Redirect to this URL after leaving Dial. See the action Request Parameters table 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 (in seconds). Defaults to 14400 seconds (4 hours).

timeout integer

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

Allowed values - positive integer (seconds). 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. Defaults to Caller's callerName.

confirmSound string

Is a remote URL fetched with POST HTTP request which 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.

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

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

The other value which can be used is real. Setting dialMusic to real will play the real ringtone of the called party. This is also the default behavior if dialMusic has not been specified.

Allowed values - a fully qualified URL or real.

callbackUrl string

URL that is notified by Plivo when one of the following events occur:

  • called party answers the call
  • called party is connected with caller
  • called party hangs up
  • caller has pressed any digit See the callbackUrl Request Parameters 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. Default is POST.

redirect boolean

If set to false, do not redirect to action URL.

We expect an XML 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.

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 comma

sipHeaders string

The 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 headers key. Only [A-Z], [a-z], [0-9] and '%' characters are allowed for SIP headers value (so you can URL encode this value).

Allowed values - List of SIP headers to send, separated by commas. Sent as key=value pair. For e.g head1=val1,head2=val2,...,headN=valN.

Parameters sent to action URL

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

DialRingStatus

This indicates if the Dial attempt rang. It can be true or false.

DialHangupCause

The standard telephony hangup cause.

DialStatus

Status of the dial. Can be completed, busy, failed, timeout or no-answer.

DialALegUUID

CallUUID of A leg.

DialBLegUUID

CallUUID of B leg. Empty if nobody answers.

Parameters sent to callbackUrl

The following parameters are sent to the callbackUrl, if specified.

DialAction

answer or connected or hangup or digits

DialBLegStatus

This indicates if B leg answered or hung up. Can be answer or connected or hangup.

DialALegUUID

CallUUID of A leg.

DialBLegUUID

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

DialDigitsPressedBy

This will return the leg of the call on which the digits were pressed (i.e., 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 this guide for a comprehensive list of hangup causes and sources.

DialBLegHangupCauseCode

A unique integer code for the hangup cause. Refer to this guide for a comprehensive list of hangup causes and sources.

DialBLegHangupSource

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

Refer to this guide for a comprehensive list of hangup causes and sources.