XML Reference

Control call flow and behavior using XML instructions. Build interactive voice response (IVR) systems, handle call routing, play media, record calls, and create dynamic telephony applications using Vobiz XML.

What is Vobiz XML?

Vobiz XML is a markup language that instructs the Vobiz platform on how to handle voice calls. When your application receives a webhook for an incoming or outgoing call, you respond with XML instructions that tell Vobiz what to do with the call - play audio, record the conversation, dial another number, collect user input, and more.

Declarative syntax: Simple, readable XML structure for call control
Event-driven: Respond to call events with XML instructions via webhooks
Composable: Combine multiple elements to create complex call flows
Dynamic: Generate XML programmatically based on business logic

How XML Works

Request-Response Flow

Call Event Occurs

An incoming call arrives, or an outbound call connects. Vobiz needs instructions on what to do next.

Webhook Request

Vobiz sends an HTTP POST request to your configured Answer URL or Action URL with call details (caller ID, call ID, DTMF digits, recording URL, etc.).

Your Application Responds with XML

Your server processes the request (query database, check business rules, etc.) and returns XML instructions telling Vobiz what to do with the call.

Vobiz Executes XML

Vobiz parses your XML and executes the instructions in order - playing audio, collecting input, dialing numbers, recording, etc.

Loop Continues

If your XML includes action URLs (e.g., after recording or input collection), Vobiz requests new XML from those URLs and the cycle continues.

Example: Simple IVR Flow

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Speak>Welcome to Vobiz! Press 1 for sales, 2 for support, or 0 for operator.</Speak>
    <Gather numDigits="1" timeout="10" action="https://yourapp.com/handle-menu">
        <Speak>We did not receive your input.</Speak>
    </Gather>
</Response>

XML Elements

Vobiz XML consists of three types of elements: the root Response element, verb elements that perform actions, and noun elements that modify verbs.

Response Element

<Response>→

The root element that wraps all other XML elements. Every XML document must have exactly oneResponse element.

Verb Elements (Actions)

Verb elements instruct Vobiz to perform specific actions during a call. They are the primary building blocks of your call flow.

<Speak>→

Convert text to speech and play it to the caller

<Play>→

Play an audio file (MP3, WAV) from a URL

<Dial>→

Dial a phone number or SIP address

<Record>→

Record the call audio

<Gather>→

Collect speech or DTMF input

<Hangup>→

Terminate the call

<Redirect>→

Transfer control to a different URL

<Wait>→

Pause execution for a specified duration

<Conference>→

Connect caller to a conference room

<DTMF>→

Send DTMF tones during a call

<PreAnswer>→

Answer call in early media mode

<Stream>→

Stream call audio to external service

<MultiPartyCall>→

Manage multi-party call sessions

Noun Elements (Modifiers)

Noun elements are nested inside verb elements to modify their behavior. They provide additional context and options for the parent verb.

<Request>→

Nested within certain elements to make HTTP requests with custom parameters

Getting Started

Basic Example

Here's a simple example that demonstrates answering a call, playing a message, and hanging up:

Hello World - XML Response

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Speak>Hello! Welcome to Vobiz telephony platform.</Speak>
    <Hangup/>
</Response>

Interactive IVR Example

A more advanced example showing user input collection and conditional routing:

IVR Menu - XML Response

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather
        numDigits="1"
        timeout="10"
        finishOnKey="#"
        action="https://yourapp.com/menu-choice"
        method="POST">
        <Speak>
            Press 1 for account information.
            Press 2 to speak with a representative.
            Press 9 to repeat this menu.
        </Speak>
    </Gather>
    <Speak>We didn't receive any input. Goodbye!</Speak>
    <Hangup/>
</Response>

Call Recording Example

Record a voicemail message with a beep before recording:

Voicemail Recording - XML Response

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Speak>Please leave a message after the beep.</Speak>
    <Play>https://yourcdn.com/beep.mp3</Play>
    <Record
        maxLength="120"
        timeout="5"
        finishOnKey="#"
        action="https://yourapp.com/recording-complete"
        recordSession="false"/>
    <Speak>Thank you for your message. Goodbye!</Speak>
    <Hangup/>
</Response>

Best Practices

Keep It Simple

Start with basic XML and gradually add complexity. Test each element thoroughly before combining multiple actions.

Set Timeouts

Always set appropriate timeouts for Gather to handle non-responsive callers gracefully.

Handle Errors

Provide fallback actions when input collection fails or URLs are unreachable. Always have a path to Hangup or Redirect.

Log Everything

Log all webhook requests and your XML responses for debugging. Use unique identifiers to trace call flows through your system.

User-Friendly Prompts

Write clear, concise voice prompts. Avoid jargon and provide obvious choices. Repeat options when users don't respond.

Valid XML

Ensure your XML is well-formed with proper opening/closing tags, escaped special characters (&, <, >, "), and UTF-8 encoding.

Incoming Carrier

Stream