> ## Documentation Index > Fetch the complete documentation index at: https://docs.vobiz.ai/llms.txt > Use this file to discover all available pages before exploring further. # Dial XML Element – Bridge Calls & Forward to Numbers | Vobiz > Bridge live callers to one or multiple numbers with the Vobiz Dial element. Supports caller ID override, answer detection, timeout, and post-dial action URLs. The Dial element dials one or multiple phone numbers and connects them to the current caller. If the call is answered, the caller and receiver are connected and can communicate until either party hangs up. If the call is not answered, a busy signal is received, or the dialed number does not exist, the Dial element ends. 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 continues 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 * Nest a [`Number`](/xml/dial/number) or [`User`](/xml/dial/user) element within the Dial element. * Specify a single Number or User value to dial a single number or SIP user. * Specify multiple Number and User elements for simultaneous dialing. The first party to answer is bridged; the rest are hung up. * You can also nest a [`Record`](/xml/record) element inside `Dial` (with `startOnDialAnswer="true"`) to record the bridged leg. * A plain phone number may be supplied as the text content of `Dial` as shorthand for a single `Number`, but using an explicit `Number`/`User` child is recommended. ## Attributes **`action`** *(string)* *Callback-retry configurable* Redirects 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)* HTTP method used to send the request to the action URL. **Allowed values:** GET, POST Defaults to POST. **`hangupOnStar`** *(boolean)* Allows the caller to press \* to hang up on the called party and continue with other operations depending on the application's response. **Allowed values:** true, false Defaults to false. **`timeLimit`** *(integer)* Sets the maximum duration of the call in seconds. **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 number of seconds the called party has to answer the call (pick up the phone or tap the answer button on a smartphone or SIP phone). **Allowed values:** positive integer No default value. **`callerId`** *(string)* Overrides the caller number with this value. **Allowed values:** valid phone number Defaults to the current caller's callerId. **`callerName`** *(string)* Overrides the caller name with this value. **Allowed values:** Any string, maximum of 50 characters Defaults to caller's callerName. **`confirmSound`** *(string)* *Callback-retry configurable* A remote URL fetched via POST that must return an XML response containing only Play, Wait, and/or Speak elements (all others are ignored). The audio 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 that starts after the call is answered. Applies only when `confirmSound` is specified without `confirmKey`. **Note:** The `confirmTimeout` value must be greater than the duration of `confirmSound` to auto-answer the call once `confirmSound` finishes playing. 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* Audio played to the caller while the call is being connected. Specify a remote URL fetched via POST that must return an XML response containing only Play, Wait, and/or Speak elements (all others are ignored). Setting `dialMusic` to `real` plays the actual ringtone of the called party. This is also the default behavior when `dialMusic` is not specified. **Allowed values:** a fully qualified URL or `real` **`callbackUrl`** *(string)* *Callback-retry configurable* URL notified when any of these events occur: * Called party answers the call * Called party is connected with the 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 When `confirmSound` and `confirmKey` are configured, the `callbackUrl` is invoked after the called party answers but before they confirm the call. **`callbackMethod`** *(string)* HTTP method used to notify the `callbackUrl`. **Allowed values:** GET, POST Defaults to POST. **`redirect`** *(boolean)* If set to `false`, the action URL is not fetched after the call. If set to `true`, Vobiz fetches the action URL and controls the call based on the XML returned. **Allowed values:** true, false Defaults to true. **`digitsMatch`** *(string)* A list of digit patterns; when the digits pressed by the caller (A leg) match a pattern, the match is sent to the `callbackUrl`. **Allowed values:** list of digit patterns separated by a comma. Example: digitsMatch="123,456,789" **`digitsMatchBLeg`** *(string)* A list of digit patterns; when the digits pressed by the called party (B leg) match a pattern, the match is sent to the `callbackUrl`. **Allowed values:** list of digit patterns separated by a comma. Example: digitsMatchBLeg="123,456,789" **`sipHeaders`** *(string)* SIP headers are always prefixed with `X-VH-`. The SIP headers are included in every HTTP request made for the dialed leg. Only \[A-Z], \[a-z], and \[0-9] characters are allowed in SIP header key names and values, which can be URL-encoded. **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` | Whether the Dial attempt rang. **Allowed values:** true, false `DialHangupCause` The standard telephony hangup cause. `DialStatus` The status of the dial. **Allowed values:** completed, busy, failed, cancel, timeout, no-answer `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:** answer, connected, hangup, digits `DialBLegStatus` Whether B leg answered or hung up. **Allowed values:** answer, connected, hangup `DialALegUUID` CallUUID of A leg. `DialBLegUUID` CallUUID of B leg. Empty if nobody answers. `DialDigitsMatch` The digits pressed by A leg that matched a pattern set in the `digitsMatch` attribute. Only available when `DialAction` is set to `digits`. `DialDigitsPressedBy` The leg of the call on which the digits were pressed - ALeg or BLeg. `DialBLegDuration` Call duration in seconds for B leg. Only available when `DialAction` is set to `hangup`. `DialBLegBillDuration` Billed call duration in seconds for B leg. Only available when `DialAction` is set to `hangup`. `DialBLegFrom` Caller number or SIP endpoint for B leg. Only available when `DialAction` is set to `answer`, `connected`, `digits`, or `hangup`. `DialBLegTo` 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:** Details about the attestation assigned to the call by Vobiz. **For inbound calls:** 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 with authorized access to the caller ID, and can be treated with confidence. Equivalent to attestation level A. * **Not Verified** means the caller is not verified, it is uncertain whether they have access to the caller ID used, or both. Equivalent to attestation level B or C. * **Not Applicable** means STIR/SHAKEN does not apply to this call - for example, if the call is not addressed to a US number or if it is a cloud call (WebRTC or SIP). Read more about STIR/SHAKEN here. ## Examples ### Bridge the caller to a single number ```xml theme={null} Connecting you to an agent. Please hold. 14155551234 Sorry, no one is available right now. ``` ### Ring multiple numbers at once The first party to answer is bridged; the others are dropped. See [Simultaneous dialing](/xml/dial/simultaneous-dialing). ```xml theme={null} 14155551111 14155552222 sip:agent3@yourdomain.vobiz.ai ``` ### Require the agent to press a key before connecting Use `confirmSound` and `confirmKey` so the agent confirms before the caller is bridged - useful to avoid connecting to voicemail. See [Confirm to answer a call](/xml/dial/confirm-to-answer-call). ```xml theme={null} 14155551234 ``` ## Webhook payload sent to the action URL After the dial ends, Vobiz posts the standard call parameters plus the Dial result parameters to the action URL. Return fresh XML (with `redirect` left at its default `true`) to continue the flow. ```http Answered then hung up theme={null} POST /dial-result HTTP/1.1 Host: yourapp.com Content-Type: application/x-www-form-urlencoded CallUUID=xyz789&From=14155551234&To=14155559999&Direction=inbound&DialStatus=completed&DialRingStatus=true&DialHangupCause=NORMAL_CLEARING&DialALegUUID=xyz789&DialBLegUUID=abc456 ``` ```http No one answered theme={null} POST /dial-result HTTP/1.1 Host: yourapp.com Content-Type: application/x-www-form-urlencoded CallUUID=xyz789&From=14155551234&To=14155559999&Direction=inbound&DialStatus=no-answer&DialRingStatus=true&DialALegUUID=xyz789&DialBLegUUID= ``` ## Edge cases and tips * **Handle every `DialStatus`.** The action URL receives `DialStatus` set to `completed`, `busy`, `failed`, `cancel`, `timeout`, or `no-answer`. Branch on it: bridge succeeded only when `completed`; for `busy`/`no-answer`/`timeout` offer voicemail or retry. `DialBLegUUID` is empty when nobody answered. * **`timeout` is the ring timeout.** `timeout` (on `Dial` or `Number`) sets how long the called party has to answer before Vobiz gives up - this is the attribute that produces `DialStatus=timeout`/`no-answer`. Do not confuse it with `timeLimit`, which caps the total bridged call duration. (Note: `Gather` uses `executionTimeout`, not `timeout`.) * **`redirect="false"` keeps the current flow.** With `redirect="false"`, Vobiz still requests the action URL but ignores any XML it returns and continues with the elements after `Dial`. Use this when you want post-dial logging without handing control to the action URL. * **`Number` vs `User`.** Use [`Number`](/xml/dial/number) for PSTN phone numbers (mobile/landline) in E.164 form. Use [`User`](/xml/dial/user) for SIP endpoints (`sip:user@domain`) and registered Browser SDK/softphone users. You can mix both in one `Dial` for simultaneous ringing. * **Reach an extension with `sendDigits`.** To navigate an extension after answer, set `sendDigits` on the `Number`/`User` child (for example `sendDigits="wwww2410"`), where each `w` waits 0.5 s. * **`callbackUrl` vs `action`.** `callbackUrl` fires live, mid-dial events (answer, connected, hangup, matched digits) and expects no XML. `action` fires once after the dial completes and drives the next flow step. Use both together when you need real-time notifications and post-dial routing. * **`dialMusic="real"` plays the real ringback.** This is the default. Provide a `dialMusic` URL only when you want custom audio while connecting.