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, Record, Redirect, Reject, or Hangup), 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, without parsing or validating it. 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. The trade-off: you get PBX-level errors, not Sautikit validation errors, when it is wrong.

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 without Sautikit validation. 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; because Sautikit does not parse it, any errors surface as PBX-level failures rather than Sautikit validation errors.

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"
  }
}

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 a conference room with startOnEnter: false rather than a dedicated queue verb.

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