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, Plivo 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.
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
action stringCallback-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 Allowed values: GET, 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: |
timeLimit integer | Used to preset the duration (in seconds) of the call. Allowed values: positive integer |
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 |
callerId string | If set to a string, caller number will be set to this string value. Allowed values: valid phone number |
callerName string | If set to a string, caller name will be set to this string value. Allowed values: Any string, maximum of 50 characters |
confirmSound stringCallback-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 Allowed values: a fully qualified URL |
confirmTimeout string | Timeout starts after the call is answered. Entertained only if Note: Defaults to: 120 |
confirmKey string | The digit to be pressed by the called party to accept the call. Used in conjunction with Allowed values: any digit, #, * |
dialMusic stringCallback-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 Allowed values: a fully qualified URL or |
callbackUrl stringCallback-retry configurable | URL to be notified when one of these events occur:
Allowed values: a fully qualified URL Configuring |
callbackMethod string | Method used to notify Allowed values: GET, POST |
redirect boolean | If set to We expect an XML response from the Allowed values: |
digitsMatch string | A list of digits that are sent to the 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 Allowed values: list of digit patterns separated by a comma. Example: digitsMatchBLeg=“123,456,789” |
sipHeaders string | SIP headers are always prefixed with 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.
DialRingStatus | Indicates whether the Dial attempt rang. Allowed values: |
DialHangupCause | The standard telephony hangup cause. |
DialStatus | Status of the dial. Allowed values: |
DialALegUUID | CallUUID of A leg. |
DialBLegUUID | CallUUID of B leg. Empty if nobody answers. |
Parameters sent to callbackUrl
These parameters are sent to the callbackUrl
, if specified.
DialAction | Allowed values: |
DialBLegStatus | Indicates whether B leg answered or hung up. Allowed values: |
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 Only available when |
DialDigitsPressedBy | Returns the leg of the call on which the digits were pressed — |
DialBLegDuration | Dial duration in seconds from B leg. Only available when |
DialBLegBillDuration | Dial duration in seconds billed from B leg. Only available when |
DialBLegFrom | Dial caller number or SIP endpoint for B leg. Only available when |
DialBLegTo | Dial called number or SIP endpoint for B leg. Only available when |
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: Refer to our list of hangup causes and sources. |
STIRVerification string | For outbound calls: Gives details about the attestation assigned to the call by Plivo For inbound calls: Gives details about the attestation received on the inbound call to your Plivo phone number. Possible values:
Read more about STIR/SHAKEN here. |
The next few sections show code for several dialing examples.