Dial XML element

Use <Dial> to create one or more B-legs and bridge the first successful destination to the current A-leg. Nest <Number> for a PSTN destination or <User> for a SIP or registered WebRTC user.

For PSTN forwarding and transfer flows, set callerId to a Vobiz number owned or authorized by your account.If you omit callerId, Vobiz derives it from the existing A-leg. B-leg creation may fail if that number is not authorized for outbound calling. Use E.164 format, such as +14155550100.

How Dial works

Vobiz creates the dialed B-leg or B-legs.
callbackUrl receives real-time answer, connected, digits, and hangup events.
Vobiz bridges the successful B-leg to the current A-leg.
action receives one final result after Dial finishes.
redirect determines whether Vobiz executes XML returned by action.

callbackUrl and action serve different purposes. Use callbackUrl to observe the B-leg while it is active. Use action to receive the final result and optionally choose the next call-control step.

Child elements

Child	Use
`Number`	Dial an E.164 PSTN phone number.
`User`	Dial a SIP URI or registered Vobiz WebRTC/SIP user.

You can include multiple child destinations for simultaneous dialing. Vobiz attempts sibling destinations concurrently and bridges the first one that answers successfully. See Simultaneous dialing. You can also place one phone number directly inside <Dial> as shorthand, but an explicit <Number> child is easier to extend with attributes and callbacks.

Attributes

Attribute	Description
`action` string	Final result URL requested after Dial finishes. Use the `redirect` attribute to control whether Vobiz executes XML returned by this URL.
`method` string	HTTP method for `action`. Values: `GET`, `POST`. Default: `POST`.
`callbackUrl` string	URL that receives real-time B-leg lifecycle events.
`callbackMethod` string	HTTP method for `callbackUrl`. Values: `GET`, `POST`. Default: `POST`.
`redirect` boolean	Controls the response from `action`. With `true`, Vobiz requests `action` and executes its returned XML. With `false`, Vobiz still sends the final Dial result to `action` but does not use the returned XML to redirect call control. Default: `true`.
`callerId` string	Caller number presented on the B-leg. For PSTN calls, use an owned or authorized Vobiz number in E.164 format. If omitted, Vobiz derives the value from the A-leg.
`callerName` string	Caller name passed toward the B-leg. The destination carrier and device decide whether to display it.
`timeout` integer	Maximum number of seconds to wait for a B-leg to answer. Set this explicitly for predictable routing behavior.
`timeLimit` integer	Maximum connected duration of the B-leg in seconds. This timer begins after the B-leg connects; ringing time is not included. Default: `14400` seconds.
`hangupOnStar` boolean	When `true`, pressing `*` on the A-leg ends the bridge. Default: `false`.
`dialMusic` string	URL that returns `<Play>`, `<Speak>`, and/or `<Wait>` instructions for the A-leg while Vobiz connects the destination. Use `real` for the ordinary ringback path. Default: `real`.
`confirmSound` string	URL requested after the B-leg answers. It must return XML containing only `<Play>`, `<Speak>`, and/or `<Wait>`.
`confirmKey` string	Digit configured with `confirmSound`. Values: `0`–`9`, `#`, or `*`. Enforcement as an acceptance gate is currently unverified, so do not depend on a keypress to control whether the B-leg connects.
`confirmTimeout` integer	Confirmation window after the B-leg answers. Set it explicitly when you use confirmation audio.
`digitsMatch` string	Comma-separated patterns to match digits pressed on the A-leg. Matching digits produce a `DialDigitsMatch` callback.
`digitsMatchBLeg` string	Comma-separated patterns to match digits pressed on the B-leg. Matching digits produce a `DialDigitsMatch` callback.
`sipHeaders` string	Comma-separated `key=value` metadata pairs. Vobiz adds the `X-VH-` prefix to these values in Dial webhooks.

timeout and timeLimit control different phases. timeout covers the unanswered ringing phase. timeLimit covers only the connected bridge.

Callback lifecycle

Callback channels

Channel	When it fires	What to return
`callbackUrl`	During B-leg answer, connection, matching digits, and hangup events.	A successful HTTP response. Returned XML does not control the call.
`action`	Once after the Dial attempt finishes.	Return XML only when `redirect="true"` and you want Vobiz to continue with a new flow.

Both channels support GET and POST. If you omit method or callbackMethod, Vobiz uses POST.

Real-time events sent to callbackUrl

`Event`	`DialAction`	Purpose	Typical event-specific fields
`DialAnswer`	`answer`	The B-leg answered.	`DialBLegUUID`, `DialBLegStatus`, `DialBLegFrom`, `DialBLegTo`, `DialBLegPosition`
`DialConnected`	`connected`	The B-leg connected to the A-leg.	`DialBLegUUID`, `DialBLegStatus`, `DialBLegFrom`, `DialBLegTo`, `DialBLegPosition`
`DialDigitsMatch`	`digits`	A configured A-leg or B-leg digit pattern matched.	`DialDigitsMatch`, `DialDigitsPressedBy`
`DialHangup`	`hangup`	The B-leg ended or a non-winning simultaneous leg was cancelled.	Duration, bill duration, hangup cause, code, name, and source

Common fields include CallUUID, DialALegUUID, DialBLegUUID, DialBLegFrom, DialBLegTo, and DialBLegPosition. Not every field is present on every event. STIRVerification may also appear on applicable calls. Values are Verified, Not Verified, or Not Applicable, depending on the call direction, attestation, destination, and whether STIR/SHAKEN applies. The values observed for DialDigitsPressedBy are:

aleg for a match from digitsMatch
bleg for a match from digitsMatchBLeg

Final fields sent to action

Field	Description
`Event`	Final callback event type.
`DialStatus`	Final Dial result, such as `completed`, `busy`, `failed`, `cancel`, `timeout`, or `no-answer`.
`DialRingStatus`	Platform ring-status value. Do not use it as proof that the destination handset physically rang.
`DialHangupCause`	Final Dial hangup cause.
`DialALegUUID`	A-leg identifier.
`DialBLegUUID`	B-leg identifier. It may be empty when no B-leg was created or answered.

See Dial status reporting for request examples and failure handling.

DTMF matching

Use digitsMatch and digitsMatchBLeg when you need real-time callbacks for keypad input during a bridge.

A-leg digits
B-leg digits

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial
      callerId="+14155550100"
      callbackUrl="https://example.com/dial-events"
      callbackMethod="POST"
      digitsMatch="123">
    <Number>+14155550101</Number>
  </Dial>
</Response>

A matching callback contains DialAction=digits, DialDigitsMatch=123, and DialDigitsPressedBy=aleg.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial
      callerId="+14155550100"
      callbackUrl="https://example.com/dial-events"
      callbackMethod="POST"
      digitsMatchBLeg="456">
    <Number>+14155550101</Number>
  </Dial>
</Response>

A matching callback contains DialAction=digits, DialDigitsMatch=456, and DialDigitsPressedBy=bleg.

Complete PSTN transfer with recording

Place a self-closing <Record/> before <Dial> to record the full session, including bridged audio. This example uses redirect="false", so action receives the final Dial result but its response does not replace the remaining XML flow.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Record
      fileFormat="mp3"
      recordSession="true"
      maxLength="3600"
      callbackUrl="https://example.com/recording-ready"
      callbackMethod="POST"
      redirect="false"
      playBeep="false"/>

  <Dial
      callerId="+14155550100"
      timeout="30"
      timeLimit="1800"
      sipHeaders="Reason=billing,Reference=abc123"
      callbackUrl="https://example.com/dial-events"
      callbackMethod="POST"
      action="https://example.com/dial-result"
      method="POST"
      redirect="false">
    <Number sendDigits="wwww2410">+14155550101</Number>
  </Dial>

  <Hangup/>
</Response>

Your application must replace the example caller ID with an owned or authorized Vobiz number. Vobiz does not expand placeholders such as {{caller_id}}; render application values before you return the XML. A transferred call runs as two legs with two CDRs and two charges. See Transferred calls end to end for the webhook order, leg correlation, and billing.

Dial a SIP or WebRTC user

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial
      timeout="30"
      timeLimit="1800"
      callbackUrl="https://example.com/dial-events"
      callbackMethod="POST"
      action="https://example.com/dial-result"
      method="POST"
      redirect="false">
    <User sipHeaders="Reason=transfer,Reference=abc123">
      sip:agent@example.com
    </User>
  </Dial>
  <Hangup/>
</Response>

For registered Vobiz SIP/WebRTC users, Vobiz sends answer, connected, and hangup events through the same Dial callback lifecycle.

No-answer behavior

When the configured answer window expires, the real-time hangup callback can report:

Event=DialHangup
DialAction=hangup
DialBLegHangupCause=NO_ANSWER
DialBLegHangupCauseCode=6010
DialBLegHangupCauseName=Ring Timeout Reached
DialBLegHangupSource=Vobiz

The final action request reports DialStatus=no-answer and DialHangupCause=NO_ANSWER. A final DialBLegUUID may be empty for this outcome.

XML Overview

Dial XML element

How Dial works

Child elements

Attributes

Callback lifecycle

Callback channels

Real-time events sent to callbackUrl

Final fields sent to action

DTMF matching

Complete PSTN transfer with recording

Dial a SIP or WebRTC user

No-answer behavior

Next steps

​How Dial works

​Child elements

​Attributes

​Callback lifecycle

​Callback channels

​Real-time events sent to callbackUrl

​Final fields sent to action

​DTMF matching

​Complete PSTN transfer with recording

​Dial a SIP or WebRTC user

​No-answer behavior

​Next steps

How Dial works

Child elements

Attributes

Callback lifecycle

Callback channels

Real-time events sent to callbackUrl

Final fields sent to action

DTMF matching

Complete PSTN transfer with recording

Dial a SIP or WebRTC user

No-answer behavior

Next steps