VoxML — call-control language

Overview

A VoxML document is a JSON array of verb objects. Each object carries a "verb" discriminator plus the verb's attributes as camelCase fields. voxio executes the verbs strictly in order; when the end of a document is reached without a transfer of control, the call is hung up (TwiML semantics).

[
  { "verb": "answer" },
  { "verb": "say",  "text": "Welcome to voxio." },
  { "verb": "pause", "length": 1 },
  { "verb": "play", "url": "https://cdn.example.com/jingle.mp3" },
  { "verb": "hangup" }
]

Unknown verbs and unknown fields are rejected at parse time — a typo fails fast with a clear error instead of silently doing nothing.

Documents

A flow execution is a chain of one or more documents:

• The initial document starts the flow (stored with an inbound number, posted inline as playbook, or fetched from playbook_url on an outbound call).
• Control transfers — a redirect, or the actionUrl of a gather/record/dial — fetch a new document over HTTPS that replaces the current one. Local branches (routines-form documents, below) transfer control without any network involved.
• The chain ends with a hangup verb, the end of a document/routine, the caller hanging up, the fetch limit (default 10 documents per call), or the branch limit (50 routine jumps per document).

Routines-form documents

Besides the flat verb array, a document can be an object with named routines and an optional session block — a complete call plan, every outcome included, in one self-contained payload. gather and dial jump between routines via branches; no mid-call fetch means no application-server dependency while a call is live.

{
  "session": {
    "id": "sess_8f3a2b91",                         // your correlation key — echoed in every webhook
    "callbackUrl": "https://app.example.com/voxio",  // receives session.* and playbook.branch events
    "callbackToken": "whsec_…"                       // HMAC signing secret for those events
  },
  "routines": {
    "main": [ /* entry routine — required */ ],
    "accepted": [ /* … */ ],
    "goodbye": [ /* … */ ]
  }
}

• Execution starts at main; reaching a routine's end without a transfer hangs up (TwiML semantics).
• gather branch keys: the collected digits (exact match), timeout (no input), default (any other digits). dial branch keys: completed, busy, no-answer, failed, screen-timeout, default.
• Branches win over actionUrl; an unmatched outcome falls back to actionUrl (when set) or falls through.
• Every branch taken emits a fire-and-forget playbook.branch webhook (to the session callback when declared) — full path visibility without being in the control loop.
• Branch targets are validated at parse time; unknown routines are rejected before the call runs.
• The session.id is attached to all webhooks for the call (payloads + X-Voxio-Session header) and to voxio's logs — grep by your ID, not voxio's SIDs.
• A limit verb inherits callbackUrl/callbackToken from the session block when it doesn't carry its own.
• A call has at most one session, armed by the first document that carries a session block. When the first document has none (e.g. an inbound number's stored redirect), the first fetched document that carries one arms it; a later document never re-arms or replaces an armed session.

TwiML compatibility

Anywhere a document is accepted — stored on a number, posted inline, or returned by your server from a fetch (any Content-Type) — a TwiML XML document works too. Voxio detects the leading < and translates the verbs to their JSON equivalents before ordinary validation. Existing Twilio voice endpoints can usually be pointed at voxio unchanged.

• Supported verbs: Say (voice, loop), Play (loop), Pause, Hangup, Redirect, Gather (numDigits, finishOnKey, timeout, action, nested Say/Play/Pause prompt; DTMF only), Record (action, maxLength, finishOnKey, playBeep), Dial (callerId, timeout, action; plain text or one bare <Number>), and Reject (approximated as hangup — voxio has no pre-answer reject).
• Twilio defaults are materialized: a Gather without finishOnKey gets "#"; a Record without playBeep beeps — migrated documents behave as they did on Twilio.
• Ignored attributes (no-ops under voxio's execution model): method everywhere (voxio always POSTs), language, bargeIn (prompts are always interruptible), actionOnEmptyResult, trim, hangupOnStar, Record timeout.
• Hard errors — anything that would silently change call behavior: TwiML verbs with no translation (<Enqueue>, <Connect>, <Stream>, <Sms>, … — the JSON verbs enqueue, connect, and stream are native VoxML; switch the document to JSON to use them), Dial nouns other than a bare <Number>, Gather input="speech", Play digits, Record transcribe, SSML markup inside Say, loop="0" (infinite), unknown attributes (typo safety), and relative action URLs (voxio requires absolute URLs).
• Routines, branches, the session block, background audio, and dial screening have no TwiML syntax — switch a document to JSON to use them. Translation is per-document: a TwiML document may Redirect to a JSON one and vice versa.

Where flows run

Fetch protocol

Whenever voxio fetches a document (outbound initial document, redirect, or an actionUrl), it issues an HTTP POST to your URL with the current call state as JSON:

POST {your-url}
Content-Type: application/json
User-Agent: voxio-flow/1.0
X-Voxio-Signature: t=1718100000,v1=…   // HMAC-SHA256, same scheme as webhooks

{
  "call_sid":    "CA…",
  "account_sid": "AC…",
  "room_sid":    "RM…",
  "from":        "+4915112345678",
  "to":          "+4930123456",
  "direction":   "inbound",
  "call_status": "in-progress",

  // present only on the matching action callback:
  "digits":           "42#",        // gather
  "recording_sid":    "RE…",        // record
  "dial_call_sid":    "CA…",        // dial
  "dial_call_status": "completed"   // dial: completed | busy | no-answer | failed
}

Your endpoint must respond 200 OK with the next VoxML document as the body.

• Requests are signed with your account's webhook signing secret when one is configured (X-Voxio-Signature).
• One automatic retry on network errors and 5xx responses.
• Documents are capped at 64 KiB; fetches must resolve to public addresses (no private/loopback ranges).
• Fetch latency is live silence for the caller — keep handlers fast and prefer static documents where possible.

Action callbacks

Interactive verbs hand their result to your application through their actionUrl: voxio POSTs the call state (with the verb's result fields, see above) and executes the document you return. The rest of the current document is discarded — exactly like TwiML's action.

WebRTC legs

A browser can be a first-class call participant. There are two ways in, for two different jobs:

• Inside a session — declare a participant with "to": {"type": "browser"} in a session playbook. Your backend gets a join token from POST /sessions and hands it to the browser; the browser talks to a small public, token-authed surface. No account credentials ever reach the client. This is the recommended path for anything session-shaped (advice calls, conferences, agent consoles).
• Outside sessions — the channels API: account-authenticated building blocks (/channels, /rooms, /calls) your backend composes into its own topology. The browser's SDP is proxied through your server, which holds the credentials.

Inside a session: join tokens

Declare the participant as a call object with "to": {"type": "browser"}. A browser leg is not dialed — an address on the endpoint, from and screen are parse errors on it (the accept gate lives in your UI, before the browser sends its offer). timeout is the connect window; reconnectWindow (0–300 s, default 45) is how long a disconnected browser may return before the leg ends.

{
  "session": { "id": "platform-key-123", "host": "advisor", "participants": ["customer"],
               "callbackUrl": "https://app.example.com/voxio", "callbackToken": "whsec_…" },
  "objects": {
    "advisor":  { "type": "call", "to": { "type": "browser" }, "timeout": 60, "reconnectWindow": 45 },
    "customer": { "type": "call", "to": "+4915112345678" }   // phone shorthand
  }
}

Submit via POST /v1/accounts/{account_sid}/sessions. Every WebRTC participant gets a webrtc block in the response — forward it to your frontend verbatim:

{
  "sid": "SS…",
  "status": "in-progress",
  "legs": [ … ],                // the Session resource, as GET /sessions/{sid}
  "participants": {
    "customer": { "endpoint": { "type": "phone", "address": "+4915112345678", "transport": "sip" }, "state": "queued" },
    "advisor": {
      "endpoint": { "type": "browser", "address": "advisor", "transport": "webrtc" }, "state": "awaiting_connection",
      "webrtc": {
        "join_url": "https://voxio.example/v1/webrtc/join",
        "join_token": "vjt_…",      // opaque: routes AND authorizes the offer
        "expires_at": "…",          // session teardown, not a connect deadline
        "ice_servers": [ { "urls": ["turn:…"], "username": "…", "credential": "…" } ]
      }
    }
  }
}

The browser needs only the token. The public surface is CORS-open and token-authed — three endpoints:

Minimal browser client (see /join for the full reference implementation with reconnect backoff):

const info = await post("/v1/webrtc/join/info", { token });          // ICE bootstrap
const mic  = await navigator.mediaDevices.getUserMedia({ audio: true });

const pc = new RTCPeerConnection({ iceServers: info.ice_servers });
mic.getTracks().forEach(t => pc.addTrack(t, mic));
pc.ontrack = e => { audioEl.srcObject = e.streams[0]; };             // remote audio
pc.onicecandidate = e => { if (e.candidate) post("/v1/webrtc/join/ice", {
  token, candidate: e.candidate.candidate,
  sdpMid: e.candidate.sdpMid || "", sdpMLineIndex: e.candidate.sdpMLineIndex,
}); };                                                                // (queue until answered — see /join)

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
const { sdp_answer } = await post("/v1/webrtc/join", { token, sdp_offer: offer.sdp });
await pc.setRemoteDescription({ type: "answer", sdp: sdp_answer });

pc.oniceconnectionstatechange = () => {                               // reconnect gesture:
  if (["disconnected", "failed"].includes(pc.iceConnectionState))     // new pc + re-POST the
    reconnectWithFreshPeerConnection();                               // offer, same token
};

• Invite links: https://…/join#vjt_… — the bundled invite page drives this exact flow for anyone you send the link to. The token rides the URL fragment, so it never appears in server logs.
• Token lifecycle: session-scoped — valid from creation until the leg ends, one active connection at a time. The leg's timeout separately answers "did they connect in time?" (no-answer when not). Re-mint a lost/leaked token with POST /sessions/{session_sid}/participants/{name}/webrtc (backend-authenticated; invalidates the old one).
• Early join: a browser connecting before its leg's turn (per connect_priority) parks on a solo mixer and is bridged when its turn comes — waiting-room semantics for free.
• Reconnect: on ICE disconnect the leg leaves the room and parks for reconnectWindow seconds; billing occupancy pauses the session clock meanwhile. Only when the window lapses does ended fire.
• Lifecycle events: participant.answered (ICE/DTLS up), participant.reconnecting/reconnected, participant.failed (never connected), participant.ended — signed to the session's callbackUrl. Each payload names the participant, its leg_sid and the endpoint it reaches (e.g. {"type": "browser", "address": "advisor", "transport": "webrtc"}; omitted for hunts and templated addresses).
• Try it live: the session tester builds a WebRTC session against your account and hands out invite links.

Outside sessions: the channels API

When you want your own topology instead of a session playbook, compose the account-authenticated primitives. A channel is a bare WebRTC leg; a room mixes legs; a call with room_sid bridges PSTN in. The browser never holds credentials — your backend relays the SDP:

// 1. backend: create a room
POST /v1/accounts/{sid}/rooms                          → { "sid": "RM…" }

// 2. browser → backend → voxio: channel from the browser's SDP offer
POST /v1/accounts/{sid}/channels
     { "sdp_offer": "v=0…" }
  → { "channel_sid": "CH…", "sdp_answer": "v=0…", "ice_servers": [ … ] }

// 3. trickle ICE (relay the browser's candidates)
POST /v1/accounts/{sid}/channels/CH…/ice
     { "candidate": "candidate:…", "sdpMid": "0", "sdpMLineIndex": 0 }

// 4. mix the channel into the room
POST /v1/accounts/{sid}/rooms/RM…/participants         { "channel_sid": "CH…" }

// 5. bridge a phone in — on answer the PSTN leg joins the same mixer
POST /v1/accounts/{sid}/calls
     { "to": "+4915112345678", "room_sid": "RM…" }

// teardown: DELETE the call, channel, and room (any order)

• Offer first, ICE after: the channel is created from the browser's offer, so TURN credentials arrive with the answer. Apply them best-effort (pc.setConfiguration({iceServers})) — voxio's side is publicly reachable, so host/server-reflexive candidates connect in most networks and TURN is the fallback, not the norm.
• No room required: a bare channel is already addressable — POST /channels/{sid}/playbacks plays a media-library file onto it, POST /channels/{sid}/tts speaks to it. Useful for prompts before any bridging.
• Sessions vs channels: the channels path gives you no join tokens, no reconnect window, no session billing/limits, and no participant.* events — you own the lifecycle. Prefer sessions unless you specifically need the raw building blocks.
• TURN TTL invariant: ICE credentials must outlive the longest call (TURN_CREDENTIAL_TTL, default 24 h — an expired credential kills the relay mid-call, not at connect).

Verb reference

{ "verb": "answer" }

{ "verb": "say", "text": "Your order has shipped.", "loop": 2 }

{ "verb": "play", "url": "https://cdn.example.com/chime.mp3" }

// from the account's media library, by title or by SID:
{ "verb": "play", "url": "media:welcome.mp3" }
{ "verb": "play", "url": "media:MFa1b2c3d4e5f60718293a4b5c6d7e8f90" }

// ambient music that ducks to 30% whenever anything speaks:
{ "verb": "play", "url": "https://cdn.example.com/ambient.mp3",
  "background": true,
  "duck": { "level": 0.3, "fadeInMs": 600, "fadeOutMs": 150 } }

// later:
{ "verb": "play", "background": true, "action": "stop" }

{ "verb": "pause", "length": 2 }

{
  "verb": "gather",
  "numDigits": 1,
  "timeout": 8,
  "actionUrl": "https://app.example.com/ivr/choice",
  "prompt": [
    { "verb": "say", "text": "For sales press 1. For support press 2." }
  ]
}

{
  "verb": "record",
  "playBeep": true,
  "maxLength": 120,
  "finishOnKey": "#"
}

{
  "verb": "dial",
  "to": "+4915112345678",
  "timeout": 25,
  "actionUrl": "https://app.example.com/ivr/after-dial"
}

{
  "session": {
    "id": "abc123",
    "callbackUrl": "https://app.example.com/sessions/abc123",
    "callbackToken": "whsec_…",
    "limit": {
      "maxMinutes": 30,
      "warnings": [
        { "atRemainingSeconds": 300, "say": "Your call ends in five minutes. Press 5 to extend.", "target": "caller" }
      ],
      "extendDigit": "5",
      "onExpiry": "end_session"
    }
  },
  "routines": { "main": [ /* verbs */ ] }
}

{ "verb": "redirect", "url": "https://app.example.com/flow/step2" }

{ "verb": "ask", "url": "https://agent.example/decide", "include": ["digits", "vars"],
  "onError": [ { "verb": "say", "text": "One moment please." } ] }

{ "verb": "script",
  "source": "const r = fetch('https://api.example/slots'); vars.slots = r.json().slots; return vars.slots.length ? 'offer' : 'none';",
  "exits": ["offer", "none"],
  "onError": [ { "verb": "say", "text": "Please hold." } ] }

{ "verb": "skill", "skill": "crm", "tool": "find_customer",
  "args": { "phone": "{{call.from}}" }, "saveAs": "caller",
  "onError": [ { "verb": "goto", "routine": "unknown_caller" } ] }

{ "verb": "connect",
  "agent": { "provider": "openai", "credential": "credential:openai-prod",
             "instructions": "You are the booking assistant for {{data.company}}.",
             "builtinTools": ["hangup"] },
  "branches": { "transfer": "human_agent" },
  "onError": [ { "verb": "say", "text": "One moment, connecting you." } ] }

{ "verb": "stream", "url": "wss://ears.example.com/calls", "background": true,
  "onError": [] }

{ "verb": "enqueue", "queue": "support",
  "waitPlaybook": [
    { "verb": "say", "text": "You are number {{queue.position}} in line." },
    { "verb": "play", "url": "media:hold-music" } ],
  "branches": { "timeout": "voicemail" } }

{ "verb": "dequeue", "queue": "support",
  "branches": { "empty": "no_callers" } }

{ "verb": "hangup" }

{ "verb": "start", "object": "advisor" }
{ "verb": "join" }
{ "verb": "end_session" }

Limits

Examples

Announcement (stored on an inbound number — no app server)

[
  { "verb": "say", "text": "Our office is closed. Please call again Monday from 9 AM." },
  { "verb": "hangup" }
]

Call forwarding with voicemail fallback

[
  { "verb": "say",  "text": "Connecting you now." },
  { "verb": "dial", "to": "+4915112345678", "timeout": 20 },
  // dial without actionUrl: execution continues here when the leg ends
  { "verb": "say",    "text": "Please leave a message after the beep." },
  { "verb": "record", "playBeep": true, "maxLength": 120, "finishOnKey": "#" }
]

Paid-minutes consultation — one self-contained plan (routines + limit + screened dial + hold music)

// POST /v1/accounts/{as}/calls — the advisor is the parent leg ("to"),
// the customer is the screened dial child. Every outcome is in the plan;
// voxio never fetches anything mid-call.
{
  "to": "+4930120849042",
  "from": "+4930120849000",
  "playbook": {
    "session": {
      "id": "sess_8f3a2b91",
      "callbackUrl": "https://app.example.com/voxio/sessions/sess_8f3a2b91",
      "callbackToken": "whsec_…"
    },
    "routines": {
      "main": [
        { "verb": "gather", "numDigits": 1, "timeout": 15,
          "branches": { "1": "accepted", "2": "declined", "timeout": "no_input", "default": "no_input" },
          "prompt": [ { "verb": "say", "text": "A customer is waiting. Press 1 to accept, 2 to decline." } ] }
      ],
      "accepted": [
        { "verb": "limit", "maxMinutes": 15, "startOn": "bridge",
          "warnings": [
            { "atRemainingSeconds": 300, "say": "Five minutes remaining. Press 5 to top up.", "target": "child" },
            { "atRemainingSeconds": 120, "say": "The session ends in two minutes.", "target": "parent" }
          ],
          "extendDigit": "5" },
        { "verb": "say", "text": "Calling the customer now." },
        { "verb": "dial", "to": "+4917612345678", "timeout": 30,
          "holdMusic": "https://cdn.example.com/hold-loop.mp3",
          "screen": { "say": "Your consultation begins shortly. Press 1 to start.", "digit": "1", "timeout": 15 },
          "branches": { "completed": "done", "screen-timeout": "mailbox", "default": "unreachable" } }
      ],
      "done":        [ { "verb": "say", "text": "The session has ended. Thank you." }, { "verb": "hangup" } ],
      "mailbox":     [ { "verb": "say", "text": "The customer could not be reached in person." }, { "verb": "hangup" } ],
      "unreachable": [ { "verb": "say", "text": "The customer could not be reached." }, { "verb": "hangup" } ],
      "declined":    [ { "verb": "say", "text": "Understood. The request was declined." }, { "verb": "hangup" } ],
      "no_input":    [ { "verb": "say", "text": "No input received. Goodbye." }, { "verb": "hangup" } ]
    }
  }
}

// The advisor hears hold music while the customer rings + screens (it ducks
// under limit warnings); the customer's ring + screening time costs nothing —
// the clock starts (session.started) when they press 1 and bridge. Every
// branch decision arrives as a playbook.branch webhook on the session callback,
// every event carries session_id sess_8f3a2b91 (payload + X-Voxio-Session).
// On "press 5": session.extension_requested → charge →
//   PATCH /v1/accounts/{as}/calls/{call_sid}/limit {"max_minutes": 25, "nonce": "CA…-1"}
// Settlement: bill from session.ended (billable_seconds), reconciled
// against the CDRs.

IVR menu (stored flow handing digits to an app)

// Stored on the number:
[
  {
    "verb": "gather",
    "numDigits": 1,
    "actionUrl": "https://app.example.com/ivr",
    "prompt": [
      { "verb": "say", "text": "For sales press 1. For support press 2." }
    ]
  },
  { "verb": "say", "text": "We did not receive a selection. Goodbye." }
]

// https://app.example.com/ivr receives {"digits":"1", …} and returns:
[
  { "verb": "say",  "text": "Connecting you to sales." },
  { "verb": "dial", "to": "+4930555111" }
]

Outbound notification call

// POST /v1/accounts/{as}/calls
{
  "to": "+4915112345678",
  "from": "+4930123456",
  "timeout": 25,                // stop ringing after 25 s → no_answer
  "playbook_url": "https://app.example.com/notify"
}

// https://app.example.com/notify returns:
[
  { "verb": "say", "text": "Your delivery arrives today between 2 and 4 PM.", "loop": 2 },
  { "verb": "hangup" }
]

Error handling

• Invalid document (bad JSON, unknown verb/field, limit exceeded): the document is rejected, a playbook.fetch_failed webhook fires, and the call is hung up. Stored documents are validated when you save them, so this only happens to fetched documents.
• Fetch failure (timeout, non-200 after retry): playbook.fetch_failed webhook, call hung up.
• Verb failure (e.g. say without TTS configured, unplayable media): the flow stops and the call is hung up; the reason is logged server-side.
• Caller hangs up: the executor aborts immediately, in-flight verbs are cancelled, and the room is torn down.
• Every flow emits playbook.started and playbook.completed webhooks; failures additionally emit playbook.fetch_failed.