Voice Actions DSL
Sautikit voice actions are the 12 JSON verbs your voice callback returns to control a call, up to 50 per response, with the fields each verb takes.
Sautikit voice actions are the 12 JSON verbs your voice callback returns to control a call, up to 50 per response, with the fields each verb takes.
Voice actions are the JSON verbs that control a call. When a call arrives or a step finishes, Sautikit POSTs the call state to your voice_callback_url. Your server returns a JSON object with an actions array of up to 50 verbs, and Sautikit runs them in order.
{
"actions": [
{ "say": { "text": "Habari, karibu." } },
{
"getDigits": {
"timeout": 5,
"numDigits": 1,
"nested": [
{ "say": { "text": "Bonyeza 1 kwa Kiswahili, 2 kwa English." } }
]
}
},
{ "hangup": {} }
]
}actions runs top to bottom.Check a document before you ship it with the validate_voice_actions tool on the MCP server. It rejects misspelled and unknown fields.
Return JSON. Sautikit validates it and hangs up with a logged error if a flow is malformed.
Sautikit also accepts an XML response (Content-Type: application/xml or text/xml) and runs it without validating it first. Use XML if you already have voice XML from Twilio or Africa's Talking and want to reuse it. Each verb's reference page shows both forms, JSON first.
| Verb | Key | Purpose |
|---|---|---|
| Say | say | Speak text to the caller |
| Play | play | Play an audio file to the caller |
| GetDigits | getDigits | Collect keypad digits, with an optional prompt |
| Dial | dial | Connect the caller to a phone number or SIP address |
| Conference | conference | Put the caller in a named conference room |
| Queue | queue | Hold the caller in a queue until an agent answers |
| Record | record | Record the caller and POST the recording URL to your action URL |
| Redirect | redirect | Continue the call from another URL |
| Reject | reject | Reject an incoming call as rejected or busy |
| Hangup | hangup | End the call |
| Stream | stream | Send live call audio to your WebSocket, for transcription or your own AI voice agent |
| AIAgent | aiAgent | Hand the call to one of your Sautikit AI agents (JSON only; must be the last action) |
{
"say": {
"text": "Your code is 4 8 2 1.",
"voice": "alice",
"language": "en-US",
"loop": 1
}
}text is required. voice, language and loop are optional.
{
"play": {
"url": "https://cdn.example.com/hold-music.mp3",
"loop": 0
}
}The URL must be a publicly reachable HTTPS link to a WAV or MP3 file. loop: 0 plays it once.
{
"getDigits": {
"timeout": 5,
"numDigits": 1,
"finishOnKey": "#",
"nested": [
{ "say": { "text": "Press 1 for sales, 2 for support." } }
]
}
}| Field | Meaning |
|---|---|
numDigits | Stop after this many digits |
finishOnKey | Key that ends input early. Defaults to # |
timeout | Seconds to wait for input after the prompt |
nested | say or play verbs to play while waiting |
getDigits has no follow-up URL field. When the caller has entered digits, Sautikit POSTs to the number's voice_callback_url again with the pressed keys in the body as dtmfDigits (read digits as a fallback), and your server returns the next actions:
app.post("/voice", (req, res) => {
const digits = req.body.dtmfDigits ?? req.body.digits;
if (digits === "1") {
return res.json({ actions: [{ dial: { number: "+254720000000" } }] });
}
res.json({ actions: [{ say: { text: "Goodbye." } }, { hangup: {} }] });
});See Build a voice IVR for a full menu.
{
"dial": {
"number": "+254720000000",
"callerId": "+254720000001",
"timeout": 30,
"record": "record-from-answer"
}
}Give exactly one destination:
| Field | Type | Use |
|---|---|---|
number | string | One phone number |
numbers | array of strings | Several phone numbers |
sip | string | A SIP address, for example sip:alice@pbx.example.com |
Optional: callerId, timeout (seconds to ring), record, sequential (ring numbers one after another) and first_answer_wins.
{
"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": {
"name": "support",
"waitUrl": "https://cdn.example.com/hold.mp3",
"callerId": "+254720000002",
"announceVoice": "en-GB-Standard-F"
}
}queue holds the caller in one of your workspace's queues until an agent answers, the queue's maximum wait time passes, or the caller hangs up. name is the queue's name in your workspace.
Actions placed after queue run when the caller leaves the queue without being answered. Use them to send an unanswered caller to voicemail. A caller who arrives at a full queue skips the wait and goes straight to those actions:
{
"actions": [
{ "queue": { "name": "support", "waitUrl": "https://cdn.example.com/hold.mp3" } },
{ "redirect": { "url": "https://ivr.example.com/voice/queue-timed-out" } }
]
}Hold audio. Use a waitUrl that stays the same from call to call, or set the hold audio on the queue and leave waitUrl out. If the audio cannot be played, the caller hears the queue's own hold audio, then a tone.
Announcement voice. announceVoice is the Google Cloud TTS voice used for position announcements (letters, digits and hyphens only). The default is en-GB-Standard-F.
To send a number straight to a queue without a callback, set the queue block on PUT /v1/numbers/{id}/routing.
{
"record": {
"action": "https://ivr.example.com/recording-done",
"method": "POST",
"timeout": 5,
"maxLength": 120,
"finishOnKey": "#",
"transcribe": false
}
}{
"redirect": {
"url": "https://ivr.example.com/after-hours",
"method": "POST"
}
}The call continues from the new URL, which returns its own voice actions.
{
"reject": { "reason": "busy" }
}reason is "rejected" (the default) or "busy".
{ "hangup": {} }{
"actions": [
{ "say": { "text": "Connecting you to our assistant." } },
{ "aiAgent": { "agentId": "your-agent-id" } }
]
}aiAgent must be the last action. See the aiAgent reference.
stream sends the live call's audio to your WebSocket as raw binary PCM frames, so your own service (a transcriber, or an AI voice agent such as Google Gemini Live) can process it in real time. Your server can play audio back into the call by sending binary PCM frames on the same socket. Streaming costs KES 0.50 a minute on top of the call rate.
{
"actions": [
{
"stream": {
"name": "gemini-agent",
"url": "wss://your-app.example.com/audio",
"track": "both_tracks",
"connect": true,
"outputSamplingRate": 16000,
"bidirectionalSamplingRate": 16000,
"headerMetadata": "{\"X-Tenant\":\"shop-1\",\"X-Auth\":\"abc123\"}",
"openMetadata": "{\"correlationId\":\"req-42\"}",
"statusCallback": "https://your-app.example.com/stream-status",
"statusEvents": "stream-started stream-stopped stream-error"
}
}
]
}Always set connect: true. Without it the call hangs up after about a second.
| Field | Required | Default | Purpose |
|---|---|---|---|
url | yes | none | ws:// or wss:// endpoint that receives the audio. Your server must accept the audio.drachtio.org WebSocket subprotocol. |
connect | no | none | true answers the call and holds it for as long as the stream runs. Set it whenever the stream is the call's main step. |
name | no | generated streamSid | Label echoed back in status callbacks as streamName. |
track | no | both_tracks | inbound_track (caller only), outbound_track, or both_tracks (both sides mixed to mono). |
outputSamplingRate | no | 8000 | Rate of the audio sent to your WebSocket, in Hz: 8000 or 16000. Frames are 16-bit little-endian signed PCM. |
bidirectionalSamplingRate | no | none | Rate of the audio your server sends back, in Hz. Set it whenever you play audio into the call. |
inputSamplingRate | no | the call's own rate | A hint about the source rate. It does not change the audio you receive. |
headerMetadata | no | none | A JSON object of string keys and values, as a string (auth tokens, tenant or correlation IDs). It arrives in the first WebSocket text frame as headers. It is not sent as HTTP headers. |
openMetadata | no | a small default object | A string sent in the first WebSocket text frame as metadata. If you leave out both this and headerMetadata, the first frame carries streamSid, streamName, sessionId, callerNumber and destinationNumber. |
statusCallback | no | your voice callback URL | URL for stream status callbacks. Voice actions in the response are ignored. |
statusEvents | no | stream-started stream-stopped | Space-separated list from stream-started, stream-stopped, stream-error. |
The first text frame your server receives is {"metadata": <openMetadata>, "headers": <headerMetadata>}.
For each subscribed event, Sautikit POSTs this 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>"
}Your voice callback is called again on later steps of the call (getDigits completion, StreamStopped, StreamError and Completed), not only when the call is answered. If it returns the same stream every time, the stream is started again on each one, which shows up as repeated streamSid values and StreamError callbacks. Check callSessionState: return the stream only when the call is first answered, and an empty actions array otherwise.
While the stream holds the call, your WebSocket server can control it by sending JSON text frames on the same socket. Audio keeps flowing as binary frames.
| Text frame | What happens |
|---|---|
{"event":"hangup"} | Ends the call. Your voice callback still receives Completed, and your statusCallback still receives StreamStopped if you subscribed to it. |
{"event":"end"} | Stops the stream and keeps the caller on the line. Sautikit POSTs StreamStopped to your voice callback and runs the voice actions you return, for example a say and a dial to hand the caller to a person. An empty response keeps the stream running. |
{"event":"flush"} | Drops audio you sent that has not been played yet. Use it when the caller interrupts and the queued reply should be discarded. |
A Node.js server using the ws package:
// End the call once the agent says goodbye
ws.send(JSON.stringify({ event: "hangup" }));
// Hand over to your voice callback for the next verb, keeping the caller on the line
ws.send(JSON.stringify({ event: "end" }));
// Caller interrupted: drop the queued reply audio
ws.send(JSON.stringify({ event: "flush" }));When your voice callback receives the StreamStopped POST that {"event":"end"} triggers, return the next verbs:
{
"actions": [
{ "say": { "text": "Connecting you to an agent." } },
{ "dial": { "number": "+254720000002" } }
]
}A closed socket is treated as a network failure. Sautikit reconnects to the same url up to 3 times, the first within about a second, and the caller hears silence in between. A reconnect does not POST to your voice callback, so your server sees a new WebSocket connection with no callback before it.
To end a stream on purpose:
{"event":"hangup"}. Closing the socket alone does not hang up.{"event":"end"} and return the next actions from your voice callback.stopOnClose and close the socket. The call stays held on silence until either party hangs up, so send {"event":"hangup"} first if the call should end.stopOnClose is the one stream setting that is XML only. Return it as XML with Content-Type: application/xml:
<Response>
<Stream
url="wss://your-app.example.com/audio"
connect="true"
bidirectionalSamplingRate="16000"
stopOnClose="true" />
</Response>If you are moving from an XML voice API, each XML verb has a JSON key:
| XML verb | JSON key | Notes |
|---|---|---|
<Say> | say | Same meaning |
<Play> | play | Same meaning |
<Gather> / <GetDigits> | getDigits | Uses numDigits, finishOnKey and timeout |
<Dial> | dial | Takes number, numbers or sip |
<Conference> | conference | A top-level verb, not nested inside dial |
<Queue> | queue | Verbs after it run when the caller leaves the queue |
<Record> | record | Same meaning |
<Redirect> | redirect | Same meaning |
<Reject> | reject | Same meaning |
<Hangup> | hangup | Same meaning |
<Stream> | stream | Set connect: true |
To make callers wait for an agent, use queue. Use a conference room with startOnEnter: false for a bridge you put together yourself, such as a scheduled multi-party call.
If your voice_callback_url returns a 5xx status or does not respond within 60 seconds, Sautikit hangs up the call. Respond quickly and do slow work after you have returned the actions.
If Sautikit cannot parse your JSON (unknown verb, more than 50 actions, malformed body), it logs the error and hangs up.