The <Dial> element connects the caller to another phone. When the called party picks the call, the two are connected until one hangs up. If the called party does not pick up, or if the number doesn’t exist, the <Dial> element will end.

Once the call ends, Plivo makes a GET or POST request to the ‘action’ URL if provided. The call flow will continue using the RESTXML received in response to that request.

Note: The <Number> element must be present and nested inside <Dial> for the <Dial> element to work.

Element Attributes

The <Dial> element supports the following attributes that modify its behavior:

Attribute Allowed Values Default Value
action absolute URL no default action for Dial
method GET, POST POST
hangupOnStar true, false false
timeLimit positive integer (seconds) 14400 seconds (4 hours)
timeout positive integer (seconds) none
callerId valid phone number Caller’s callerId
callerName caller name string to set Caller’s callerName
confirmSound absolute URL empty
confirmKey any digit, #, * empty
dialMusic absolute URL empty
callbackUrl absolute URL empty
callbackMethod GET, POST POST
redirect true, false true
digitsMatch List of digits patterns separated by comma empty
  • hangupOnStar: The ‘hangupOnStar’ attribute lets the calling party hang up on the called party by pressing the ‘*‘ key on their phone. When two parties are connected using <Dial>, Plivo blocks execution of further elements until one party hangs up. This feature allows the calling party to hang up on the called party without having to hang up their phone and ending their RESTXML processing session. When the caller presses ‘*‘ Plivo will hang up on the called party. If an ‘action’ URL was provided, Plivo submits ‘completed’ as the ‘DialCallStatus’ to the URL and processes the response. If no ‘action’ was provided Plivo will continue on to the next element in the current RESTXML document.
  • timeLimit: The ‘timeLimit’ attribute sets the maximum duration of the <Dial> in seconds. For example, by setting a time limit of 60 seconds <Dial> will hang up on the called party automatically one minute into the phone call. By default, there is a four hour time limit set on calls.
  • timeout: Controls how long (in seconds) to ring called party. Default not set.
  • confirmSound The ‘confirmSound’ attribute is a remote URL fetched with POST HTTP request which must return a RESTXML with Play, Wait and/or Speak Elements only (all others are ignored). This RESTXML is played to the called party when he answered.
    Note: This parameter must be specified for confirmKey to work.
  • confirmKey is a one key digit to be pressed by the called party to accept the call.
  • dialMusic The ‘dialMusic’ attribute is the music to be played to the caller while ringing.
    If set to an Url, ‘dialMusic’ is a remote URL fetched with POST HTTP request which must return a RESTXML with Play, Wait and/or Speak Elements only (all others are ignored).
    If ‘dialMusic’ is set to ‘none’, no ringback will be played.
    If ‘dialMusic’ is empty, default US ringback will be played.
  • action: Redirect to this URL after leaving conference.
  • method: Submit to ‘action’ url using GET or POST.
  • callbackUrl is an url to request when the called party is bridged with caller and when called party hangup or when caller has pressed digits matching (digitsMatch)
  • callbackMethod submit to ‘callbackUrl’ url using GET or POST
  • digitsMatch set matching key combination for the caller (A leg). List of digits patterns separated by comma.
  • redirect if ‘false’, don’t redirect to ‘action’, only request url and continue to next element.
  • callerName if not set, caller name will be the current caller name (default).
    If set to ‘none’, caller name will be blank.
    If set to a string, caller name will be set to this string value.
  • callerId if not set, caller number will be the current caller number (default).
    If set to ‘none’, caller number will be blank.
    If set to a string, caller number will be set to this string value.
Request Parameters
Parameter Description
DialRingStatus This indicates if the <Dial> attempt rang or not. It can be true or false.
DialHangupCause The reason for hanging up the bridge.
DialALegUUID CallUUID of A leg.
DialBLegUUID CallUUID of B leg. Empty if nobody answers.
CallbackUrl Request Parameters
Parameter Description
DialBLegStatus ‘answer’ or ‘hangup’. This indicates if B leg answered or hung up.
DialALegUUID CallUUID of A leg.
DialBLegUUID CallUUID of B leg. Empty if nobody answers.
DialBLegHangupCause Dial hangup cause for B leg. Only available when DialBLegStatus is ‘hangup’.

<Number> Element

The <Number> element needs to be nested within <Dial> for <Dial> to work. One <Number> can be specified for simple Dial. Simultaneous dialing is also possible using multiple <Number> elements.

Usage and Example

Usage and examples for <Dial> can be found in the documentation of element <Number>.

Similar

Check RESTAPI Call

Comments are closed.