How XML Works

Understand the request-response cycle between Vobiz and your application. Learn how XML instructions control call flow through webhooks and dynamic responses.

Event-Driven Architecture

Vobiz XML operates on an event-driven model. When call events occur (incoming call, DTMF pressed, recording complete), Vobiz sends HTTP requests to your configured URLs and executes the XML you return. This allows you to build dynamic, data-driven call flows.

Request-Response Flow

The Basic Cycle

Call Event Triggers

An incoming call arrives, an outbound call connects, a user presses a DTMF key, a recording finishes, or any other call event occurs.

Vobiz Sends Webhook

Vobiz makes an HTTP POST (or GET) request to your Answer URL or Action URL with call details: CallUUID, From, To, Direction, DTMF digits, RecordingURL, etc.

Your Server Generates XML

Your application processes the webhook data (lookup customer in database, check business rules, etc.) and returns XML instructions in the HTTP response body.

Vobiz Executes XML

Vobiz parses your XML and executes each element in order: plays audio, collects input, dials numbers, records audio, etc.

Cycle Repeats

If your XML includes action URLs (on Gather, Record, Dial, etc.), Vobiz requests new XML from those URLs and the cycle continues until the call ends or a Hangup element is reached.

Webhook Lifecycle

Answer URL (Inbound Calls)

When an incoming call arrives at your Vobiz phone number, Vobiz requests XML from the Answer URL configured in your Application settings.

POST https://yourapp.com/answer
CallUUID=abc123&From=+14155551234&To=+14155559999&Direction=inbound

Action URLs (Subsequent Events)

XML elements like Gather, Record, and Dial can specify action URLs. After the action completes, Vobiz requests new XML from that URL with event-specific parameters.

POST https://yourapp.com/menu-choice
CallUUID=abc123&Digits=1&From=+14155551234

Hangup URL (Call End)

When the call ends (hangup, timeout, network issue), Vobiz sends a final webhook to your Hangup URL with call duration, end reason, and other metadata. This is for logging/billing—no XML is expected.

POST https://yourapp.com/hangup
CallUUID=abc123&Duration=125&HangupCause=NORMAL_CLEARING

Complete Example Flow

Step 1: Incoming Call (Answer URL)

Customer calls your Vobiz number. Vobiz sends webhook to your Answer URL:

Webhook Request to Answer URL

POST /answer HTTP/1.1
Host: yourapp.com
Content-Type: application/x-www-form-urlencoded

CallUUID=xyz789&From=+14155551234&To=+14155559999&Direction=inbound

Your server returns XML to present an IVR menu:

Your XML Response

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather
        numDigits="1"
        timeout="10"
        action="https://yourapp.com/menu-choice"
        method="POST">
        <Speak>Press 1 for sales, 2 for support, 0 for operator.</Speak>
    </Gather>
    <Speak>We didn't receive your input. Goodbye!</Speak>
    <Hangup/>
</Response>

Step 2: User Presses "1" (Action URL)

Vobiz collects the digit and sends webhook to the action URL:

Webhook Request to Action URL

POST /menu-choice HTTP/1.1
Host: yourapp.com
Content-Type: application/x-www-form-urlencoded

CallUUID=xyz789&Digits=1&From=+14155551234

Your server checks the digit, looks up sales queue, returns XML to transfer:

Your XML Response

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Speak>Connecting you to sales. Please hold.</Speak>
    <Dial timeout="30" action="https://yourapp.com/dial-result">
        +14155555678
    </Dial>
    <Speak>Sorry, no one is available. Please call back later.</Speak>
    <Hangup/>
</Response>

Step 3: Call Connects or Fails

If the Dial succeeds, the calls are bridged. When one party hangs up, Vobiz sends webhook to the Dial action URL with the result, then to your Hangup URL when the call fully ends.

Key Takeaways

XML is Stateless

Each webhook is independent. Vobiz doesn't maintain call flow state—your application must track the conversation using CallUUID and database lookups.

Webhooks Must Respond Fast

Your server should return XML within 1-2 seconds. Slow responses cause dead air for callers. Do heavy processing asynchronously and cache data when possible.

Chain Actions Together

Use action URLs to build multi-step flows: collect input → validate → transfer → record → send notification. Each step is a separate webhook-XML cycle.

Always Have a Fallback

If input collection times out or a Dial fails, provide fallback XML (retry, leave voicemail, or Hangup gracefully). Never leave calls in an undefined state.

Overview

Getting Started