Skip to main content

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.

Hold music queue with round-robin agent dispatch, retry cycles, and voicemail fallback.

View on GitHub

Clone and run the full working example

​
Getting started

git clone https://github.com/vobiz-ai/Vobiz-Call-Queue-XML-Python.git
cd Vobiz-Call-Queue-XML-Python
cp .env.example .env
pip install -r requirements.txt
python server.py

​
Overview

Inbound callers hear a greeting and are placed in a queue with hold music. The server dials available agents round-robin. If no agent answers after MAX_WAIT_CYCLES attempts, the caller is offered voicemail. Agents register themselves as available or offline via a REST API. Real-time queue metrics track wait times, connections, and abandonment rate.

​
Call flow

Caller dials in
  └── /answer  → "Thank you for calling. Please hold."
        └── /queue-hold  → Play hold music (HOLD_WAIT_SECS)
              └── /queue-try-agent  → Dial next available agent (round-robin)
                    ├── Agent answers → Connected  → /dial-complete
                    └── No answer / busy
                          ├── cycles < MAX_WAIT_CYCLES → back to /queue-hold
                          └── cycles ≥ MAX_WAIT_CYCLES → /queue-voicemail
                                └── Caller leaves message → /voicemail-done

​
Vobiz webhooks

Set /answer as the Answer URL in your Vobiz application.
MethodPathDescription
POST/answerGreeting + join queue
POST/queue-holdPlay hold music + wait per cycle
POST/queue-try-agentDial next available agent (round-robin)
POST/dial-completeAgent answered or no-answer - retry or fallback
POST/queue-voicemailFallback after MAX_WAIT_CYCLES exhausted
POST/voicemail-doneRecording saved
POST/hangupCleanup + abandoned tracking

​
App API

MethodPathDescription
POST/agentsRegister agent as available {number, name}
DELETE/agents/{number}Take agent offline
GET/agentsList available agents
GET/queue/statusCallers waiting + agents available
GET/queue/metricsAvg wait, connected, abandoned, abandonment rate

​
Environment variables

VariableRequiredDescription
VOBIZ_AUTH_IDYesVobiz account auth ID
VOBIZ_AUTH_TOKENYesVobiz account auth token
FROM_NUMBERYesYour Vobiz DID
AGENT_NUMBERYesDefault agent number (fallback if none registered)
HOLD_MUSIC_URLNoURL to MP3/OGG hold music
MAX_WAIT_CYCLESNoMax hold attempts before voicemail (default: 3)
HOLD_WAIT_SECSNoSeconds of hold per cycle (default: 20)
HTTP_PORTNoServer port (default: 8000)
PUBLIC_URLNoProduction URL - skips ngrok if set
NGROK_AUTH_TOKENNongrok auth token for local dev