Voice Actions DSL

Summary

Voice Actions are the JSON DSL Sautikit uses to control call flow. When a call arrives or a step completes, Sautikit POSTs the call state to your voice_callback_url. Your server returns a JSON object with an actions array of verbs (Say, Play, GetDigits, Dial, Conference, Queue, Record, Redirect, Reject, Hangup, Stream, or aiAgent), which the platform executes in order.

JSON form and XML form

Voice actions can be expressed in two forms:

• JSON form: the native VoiceAction DSL described in this document. Sautikit parses and validates it before translating it to PBX XML, so you get clear, Sautikit-level errors when a flow is malformed. This is the format to build on.
• XML form: a raw XML body Sautikit forwards to the PBX byte-for-byte. If you are coming from Twilio (TwiML) or Africa's Talking, this is the form you already write: your existing voice XML works as-is, and it also covers the handful of cases the JSON DSL does not yet express.

Both forms are shown as tabs on each verb's reference page, with JSON as the default tab.

Runtime note: JSON is the format Sautikit parses and validates. Raw XML you return from your voice URL is forwarded to the PBX unchanged; validation, if any, happens at the PBX, not at Sautikit. Return JSON in your webhook responses unless you have a specific reason to hand the PBX raw XML.

Why a JSON DSL?

Sautikit accepts two response formats from your voice callback:

1. JSON: the VoiceAction DSL described here. Parsed and validated by Sautikit before being translated to PBX XML.
2. Raw XML: forwarded to the PBX byte-for-byte. Reach for it when you are bringing existing voice XML from Twilio or Africa's Talking, or for cases the JSON DSL does not yet cover.

The JSON DSL exists so your server can construct call flows with standard JSON libraries, receive type-checked errors from the Sautikit validator, and stay decoupled from the underlying PBX XML dialect. If you are moving from an XML-based voice API, the verb names map closely. The main difference is that Sautikit uses getDigits for DTMF collection (see the verb table below).

Response envelope

{
  "actions": [
    { "say":  { "text": "Habari, karibu Sautikit." } },
    { "getDigits": { "timeout": 5, "numDigits": 1,
        "nested": [{ "say": { "text": "Bonyeza 1 kwa Kiswahili, 2 kwa English." } }]
    }},
    { "hangup": {} }
  ]
}

• actions is ordered: verbs execute top to bottom.
• Maximum 50 verbs per response (MaxActionSteps).
• Exactly one verb key per object; all other keys must be absent.

Verb table

Verb reference

Say

{
  "say": {
    "text": "Your OTP is 4 8 2 1.",
    "voice": "alice",
    "language": "en-US",
    "loop": 1
  }
}

voice and language default to PBX defaults when omitted. loop: 0 means play once.

Play

{
  "play": {
    "url": "https://cdn.example.com/hold-music.mp3",
    "loop": 0
  }
}

The URL must resolve to a host on your workspace's CDN allow-list.

GetDigits

{
  "getDigits": {
    "timeout": 5,
    "numDigits": 1,
    "finishOnKey": "#",
    "nested": [
      { "say": { "text": "Press 1 for sales, 2 for support." } }
    ]
  }
}

nested verbs (Say or Play) play while waiting for input. finishOnKey defaults to #. When digits are collected the platform POSTs back to your voice_callback_url with the Digits field populated.

Dial

{
  "dial": {
    "number": "+254722000001",
    "callerId": "+254700000001",
    "timeout": 30,
    "record": "record-from-answer"
  }
}

Use sip instead of number to dial a SIP URI ("sip": "sip:alice@pbx.example.com"). number and sip are mutually exclusive.

Conference

{
  "conference": {
    "name": "weekly-team-call",
    "maxParticipants": 10,
    "record": true,
    "beep": true,
    "waitUrl": "https://cdn.example.com/hold.mp3",
    "statusEventsCallbackUrl": "https://ivr.example.com/conference-events",
    "statusEvents": "start end join leave"
  }
}

Queue

{
  "queue": {
    "name": "support",
    "waitUrl": "https://cdn.example.com/hold.mp3",
    "callerId": "+254712345678",
    "announceVoice": "en-GB-Standard-F"
  }
}

queue parks the caller in the phone switch's own call-centre queue. The switch owns the waiting and the matching, so:

• There is no hold ceiling. A caller waits until an agent answers, until the queue's own maxWaitTime if one is configured, or until they hang up.
• Handover is immediate. When an agent hangs up, the next waiting caller reaches them in roughly 170ms.

name is bare — no workspace prefix. There is deliberately no tenant attribute on this verb: the switch reads the workspace off the authenticated channel, so a callback cannot park its caller in someone else's queue.

Queue is not a terminal verb. Actions placed after it run when the caller leaves the queue, however that happened — which is how an unanswered caller reaches voicemail, and how a full queue (maxDepth reached) overflows, since the switch skips the park and simply continues:

{
  "actions": [
    { "queue": { "name": "support", "waitUrl": "https://cdn.example.com/hold.mp3" } },
    { "redirect": { "url": "https://ivr.example.com/voice/queue-timed-out" } }
  ]
}

Hold audio. Prefer a stable waitUrl served with real cache headers, or configure the hold audio on the queue itself and omit waitUrl entirely. The switch caches hold audio by URL, so a freshly-signed URL per call is a new cache key on every join and the file is downloaded before the caller is parked — about 0.38s, against a park-to-ring that is otherwise about 170ms. When audio cannot be played the switch falls back in order: waitUrl, then the queue's own hold audio, then a tone. A waiting caller never hears silence.

Announcement voice. announceVoice names the Google Cloud TTS voice the switch speaks position announcements in; omit it and the switch uses en-GB-Standard-F. Letters, digits and hyphens only — the value reaches a command line on the switch, so anything else is rejected rather than cleaned up. Google publishes no en-KE, en-ZA or en-NG voice, so en-GB-Standard-F is the closest neutral default for East and West African deployments alike. The Swahili sw-KE Chirp3-HD voices are available and sound good, but position announcements in Swahili would need Swahili numerals, which the switch does not yet speak.

To point a claimed number straight at a queue without writing a callback at all, set the queue block on PUT /v1/numbers/{id}/routing, which also documents the sharing_mode ring orders and the 202 provisioning response.

Record

{
  "record": {
    "action": "https://ivr.example.com/recording-done",
    "method": "POST",
    "timeout": 5,
    "maxLength": 120,
    "finishOnKey": "#",
    "transcribe": false
  }
}

Redirect

{
  "redirect": {
    "url": "https://ivr.example.com/after-hours",
    "method": "POST"
  }
}

Transfers call flow to a new URL that returns its own VoiceAction response. Use this to implement menus without a single monolithic handler.

Reject

{
  "reject": { "reason": "busy" }
}

reason is "rejected" (default) or "busy". Use busy to simulate a busy signal rather than a hard rejection.

Hangup

{ "hangup": {} }

Ends the call. No parameters required.

Stream

Stream forks the live call's audio to a WebSocket endpoint as raw binary PCM frames, so an external service (a transcriber, or an LLM voice agent such as Google Gemini Live) can process the audio in real time. In bidirectional mode, your WebSocket server plays audio back into the call by sending binary PCM frames on the same socket, which makes full-duplex AI voice agents possible.

XML form (forward this via the raw-XML response today; see the note below). This example bridges to a Gemini Live agent and passes tenant/auth context through the metadata attributes:

<Response>
  <Stream
    name="gemini-agent"
    url="wss://your-app.example.com/audio"
    track="both_tracks"
    connect="true"
    outputSamplingRate="16000"
    bidirectionalSamplingRate="16000"
    headerMetadata='{"X-Tenant":"hdty","X-Auth":"abc123"}'
    openMetadata='{"correlationId":"req-42"}'
    statusCallback="https://your-app.example.com/stream-status"
    statusEvents="stream-started stream-stopped stream-error" />
</Response>

JSON form — build it with the stream() helper in @sautikit/node (the SDK emits this shape ahead of native runtime support; see the note):

{
  "stream": {
    "name": "gemini-agent",
    "url": "wss://your-app.example.com/audio",
    "track": "both_tracks",
    "connect": true,
    "outputSamplingRate": 16000,
    "bidirectionalSamplingRate": 16000,
    "headerMetadata": { "X-Tenant": "hdty", "X-Auth": "abc123" },
    "openMetadata": "{\"correlationId\":\"req-42\"}",
    "statusCallback": "https://your-app.example.com/stream-status",
    "statusEvents": "stream-started stream-stopped stream-error"
  }
}

Your WebSocket server must accept the audio.drachtio.org subprotocol. For each subscribed event, Sautikit POSTs this payload to your statusCallback:

{
  "callSessionState":         "StreamStarted | StreamStopped | StreamError",
  "streamSid":                "MZ<epoch><rand>",
  "streamName":               "<name or sid>",
  "streamUrl":                "<wss-url>",
  "streamTrack":              "inbound_track | outbound_track | both_tracks",
  "streamInputSamplingRate":  "<hz>",
  "streamOutputSamplingRate": "<hz>",
  "streamEvent":              "stream-started | stream-stopped | stream-error",
  "streamStatus":             "active | stopped | failed",
  "errorMessage":             "<reason>"
}

Stream lifecycle

Stream forks media and returns immediately — the fork itself is fire-and-forget and does not hold the call. A document containing only Stream without connect="true" ends as soon as it is executed, and the platform hangs up the leg within about a second. connect="true" answers and holds the leg for the fork's lifetime.

Your voice callback is also re-invoked on lifecycle edges — getDigits completion, StreamStopped, StreamError, and Completed — not just the initial answer. A stateless callback that returns the same Stream document on every POST re-issues the fork each time, which shows up as repeated streamSid values and StreamError callbacks with errorMessage -ERR. Branch on callSessionState: return the Stream document only on the initial answered edge, and an empty <Response/> on every other edge.

Verb mapping for XML-based migrations

If you are moving from a PBX XML dialect, the following table shows the equivalent JSON key for each common XML verb:

For hold queues, use the queue verb. A conference room with startOnEnter: false is still the right tool for a bridge you assemble yourself — a supervisor joining a live call, or a scheduled multi-party room — but it is no longer the way to make callers wait for an agent.

Error handling

If your voice_callback_url returns a non-2xx status or does not respond within 10 seconds, the platform hangs up the call. Always respond quickly; do any heavy work asynchronously after returning the initial action set.

If the platform cannot parse your JSON (unknown verb, too many actions, malformed body), it logs the error and hangs up.

Next steps

• Voice action verb reference
• Build an IVR menu
• Webhooks: signing and delivery