Home  /  API  /  Docs

Build with Voitex

Welcome! Everything you need to build on Voitex, explained in plain words with real examples you can copy. Route calls, stream live audio to your AI, send calls and texts, and have your app running in minutes.

00 · Start here

Getting started

The two directions, your Auth-Key and your app’s signing secret. Read this first, then pick an API below.

00

Getting started

Two directions, one account. Voitex calls your webhook when a call or text comes in, and you call Voitex to send calls, texts and manage your data.

Overview

Everything is HTTPS. Voitex sends your webhook JSON; you send Voitex form fields and get JSON back. There are no SDKs to install.

APIWhat it does
VoiMLVoitex → you. Every incoming call to your numbers is POSTed to your webhook. You reply with an ordered list of actions.
Media streamsVoitex → you. Live call audio over a WebSocket to your server, and audio you send played back to the caller. See Media streams.
VoiML textsVoitex → you. Every incoming text to your numbers is POSTed to your app’s SMS URL. You reply with texts to send back. See Incoming texts.
Notify APIYou → Voitex. Send a call or a text to one number, a list, or whole contact labels, now or on a schedule.
More APIsYou → Voitex. Upload and download recordings, keep contacts in sync, pull new voicemails and send single texts.
Grouply APIYou → Voitex. Invite and remove group members, message a whole group and list its members.
To get started you need a public HTTPS endpoint that accepts JSON. Set it as your account’s webhook in the portal and every incoming call to your numbers is sent there.

Authentication

Requests you make to Voitex carry your Auth-Key header. Requests Voitex makes to your webhook, and the stream connections it opens, are signed with your app’s signing secret, so you can prove they came from us.

CredentialWhereUsed for
Auth-KeyheaderEvery Notify, recordings, contacts, voicemail, SMS and Grouply request. We give it to you when your account opens. Keep it on your server.
signing secretHMAC keyOne per VoiML app. Verifying X-Voitex-Signature on that app’s webhook requests and stream connections. See Signing.
POST /notify/header
POST https://notify.voitexapi.com/notify/
Auth-Key: your_auth_key
Content-Type: application/x-www-form-urlencoded

Send fields as form data: application/x-www-form-urlencoded, or multipart/form-data when you attach a file. Request examples below show the fields as JSON or key=value lines for readability.

APIMethodBase URL
NotifyPOSThttps://notify.voitexapi.com/notify/
RecordingsPOST · GEThttps://recording.voitexapi.com/
ContactsPOSThttps://contacts.voitexapi.com/
VoicemailGEThttps://vm.voitexapi.com/
Send SMSPOSThttps://sms.voitexapi.com/send/
GrouplyPOSThttps://grouply.voitexapi.com/
01

VoiML · Incoming calls

Our JSON call routing. Voitex sends each incoming call to your webhook and runs the actions you reply with.

How it works

A call arrives, we send you its state, you reply with an ordered list of actions. We run them top to bottom, then ask again whenever we need to know what happens next.

StepWhat happens
call.startedA call comes in. We POST you the call, you reply with actions.
runPrompts play, digits are collected and calls are dialed, in order.
ask againA gather, dial, record or player result, or a redirect, sends you the next request.
call.endedSent when the call is over, with every recording and the player’s last position.

The request

Every request is a POST with a JSON body. It always carries the call and your saved state, plus the details for that event.

POST your-app.com/voitexcall.started
{
  "version": "1.0",
  "event": "call.started",
  "call": {
    "id": "c_8f2k41",
    "from": { "number": "+12125550187", "name": "SARAH KLEIN" },
    "to":   { "did": "+12125550100" }
  },
  "state": null
}
FieldTypeDescription
versionstringPayload version. Currently "1.0".
eventstringWhat happened. See Events.
sequenceintegerOrder of this request within the call. With call.id, use it to de-duplicate.
call.idstringUnique per call. Also sent as the X-Voitex-Call-Id header.
call.from.numberstringCaller’s number, E.164.
call.from.namestringCaller ID name, when the network provides one.
call.to.didstringThe number they dialed. Use it to tell your numbers and accounts apart.
stateanyWhatever you returned last, sent back word for word. null on the first request.

The reply

Reply 200 OK with application/json: a list of actions and, if you like, new state. The whole reply is checked before anything plays.

200 OK · application/jsonactions
{
  "actions": [
    { "action": "say", "text": "Thanks for calling Riverside Academy." },
    { "action": "gather", "num_digits": 1, "timeout": 6,
      "prompts": [
        { "action": "say", "text": "Press 1 for the office, 2 for today's schedule." }
      ],
      "inputs": {
        "1": [ { "action": "dial", "extension": "101" } ],
        "2": [ { "action": "play", "url": "https://example.com/today.mp3" },
               { "action": "hangup" } ]
      }
    }
  ],
  "state": { "menu": "main" }
}
FieldTypeDescription
actionsarrayOrdered list of actions. An empty reply hangs up.
stateanyOptional. Saved and sent back on every later request for this call.

State

Return a state object and it comes back to you, word for word, on every request for that call. Use it for the menu they are in, an account you looked up, or how many times they missed a prompt.

You returnResult
"state": {…}Replaces the saved state.
no state keyKeeps the old state.
"state": nullClears it.

Instant inputs

Every request is dead air for the caller. Put the answers you already know in a gather’s inputs and they run the moment the key is pressed, up to three menus deep. Anything that depends on a lookup, like a balance or who is on shift, still goes to your server.

CallerWhat happens
a mapped keyInstant. The branch in inputs runs on the spot. No request.
any other keyAsks you. gather.completed is sent to your webhook, so you still decide.
speaksAsks you. Spoken answers always go to your webhook as gather.completed. inputs only matches keys.
nothingMoves on. The gather times out and the next action runs.

Actions

Each item in actions is an object with an action name and its options. Mix them in any order.

ActionWhat it does
saySpeak text with text-to-speech.
playPlay audio you host.
playerLong audio callers can move around in.
gatherAsk a question, collect keypresses or a spoken answer.
dialCall a number or a PBX seat.
redirectFetch and run the next document.
recordRecord the caller, get a link.
pauseAdd a moment of silence.
hangupEnd the call.
streamSend the call’s live audio to your WebSocket server, and play audio you send back.
stream_stopStop a listen-only stream.
saySpeak text with text-to-speech.

Uses your account voice unless you pick another. Set barge_in to false for a message callers must hear in full.

OptionTypeDescription
textstringWhat to say.required
voicestringOverride the account voice.
languagestringDefault en-US.
speednumber0.5 to 2.0.
barge_inbooleanLet a keypress cut it short.
sayaction
{ "action": "say", "text": "Thanks for calling.", "barge_in": false }
playPlay audio you host.

mp3, wav, ogg, flac and more. Files are fetched early, cached and re-checked hourly, so a cached clip starts instantly.

OptionTypeDescription
urlstringThe audio file.required
loopintegerRepeat up to 10 times.
barge_inbooleanLet a keypress cut it short.
playaction
{ "action": "play", "url": "https://cdn.example.com/greeting.mp3" }
playerLong audio callers can move around in.
New

For lectures, music, podcasts and audiobooks up to 3 hours and 120 MB. Map keys to seek, pause, change speed or volume, open spoken menus, or return a key to you with the exact position. Keys you don’t map do nothing, so nobody loses their place by accident. Player guide →

OptionTypeDescription
urlstringThe audio file.required
start_msintegerWhere to start, to resume. Default 0.
speednumber0.5 to 2. Default 1.
volumeinteger−6 to +6. Default 0.
controlsobjectKeys while playing. Key → control.
paused_controlsobjectKeys while paused. Key → control.
pause_timeoutintegerSeconds a caller can stay paused, 5 to 3600. Default 300.
resume_rewind_msintegerHow far to step back on resume so no word is lost. Default 500.
action_urlstringWhere player.completed is sent.

Controls

Use these in controls, in paused_controls and inside menus.

ControlValueDescription
seeksecondsJump back (negative) or forward, 1 to 3600 seconds.
pause_toggletruePause or resume.
speednumberChange speed. Their place is kept.
volumeintegerA step louder or quieter, up to ±6.
volume_cycletrueCycle 0 → +2 → +4 → 0.
volume_resettrueBack to normal volume.
moh_toggletrueWhile paused, switch between the pause beep and hold music.
returnstringStop and send player.completed to you, with this name.
menuobjectOpen a spoken menu: prompts, timeout and options (key → control). Two levels deep. Callers who know it can type straight through, like a fast 5 7.
confirmarrayOptional on any control: say or play heard after it works.

The lecture keypad

1−15 s
2Pause
3+15 s
4−1 min
5Options
6+1 min
7−5 min
8Bookmark
9+5 min
*Menu
0Previous
#Next
SeekPause / menuReturns to you
player · lecture keypadaction
{
  "action": "player",
  "url": "https://cdn.example.org/lectures/24.mp3",
  "start_ms": 0,
  "controls": {
    "1": {"seek": -15},  "3": {"seek": 15},
    "4": {"seek": -60},  "6": {"seek": 60},
    "7": {"seek": -300}, "9": {"seek": 300},
    "2": {"pause_toggle": true},
    "8": {"return": "bookmark"},
    "0": {"return": "previous"}, "#": {"return": "next"}, "*": {"return": "menu"},
    "5": {"menu": {
      "prompts": [{"action": "play", "url": "https://cdn.example.org/prompts/options.mp3"}],
      "timeout": 3,
      "options": {
        "1": {"menu": {"timeout": 3, "options": {
               "1": {"volume": -2}, "2": {"volume_reset": true}, "3": {"volume": 2}}}},
        "2": {"return": "liked"}, "3": {"return": "playlists"},
        "5": {"return": "next_date"}, "6": {"return": "skip_10"},
        "7": {"speed": 0.5, "confirm": [{"action": "say", "text": "Half speed"}]},
        "8": {"speed": 1},
        "9": {"speed": 1.5, "confirm": [{"action": "say", "text": "One and a half speed"}]}
      }}}
  },
  "paused_controls": {
    "2": {"pause_toggle": true},
    "0": {"moh_toggle": true},
    "5": {"return": "length"}
  },
  "pause_timeout": 300,
  "action_url": "/ivr/player"
}

What comes back

Every player.completed, and the player block on call.ended, reports the caller’s place and settings, accurate to about ±0.2 s. Send the same player back with them and the caller carries on as if nothing happened.

player.completedVoitex → you
{
  "event": "player.completed",
  "player": {
    "reason": "key", "name": "bookmark", "digits": "8",
    "position_ms": 1383400, "duration_ms": 2895000,
    "speed": 1.5, "volume": 2, "paused": false,
    "listened_ms": 1102000
  }
}
FieldTypeDescription
reasonstringWhy playback stopped, e.g. key.
namestringThe return name of the control that was pressed.
digitsstringThe key or keys pressed.
position_msintegerWhere they stopped. Send it back as start_ms to resume.
duration_msintegerLength of the recording.
speed · volumenumberTheir current settings.
paused · mohbooleanPaused, or paused on hold music.
listened_msintegerTime actually listened.
paused_ms · menu_msintegerTime spent paused and in menus.
Voitex reports positions; bookmarks, likes, playlists and listening history are yours to keep in your own system. If the caller hangs up mid-recording, call.ended brings their position as an automatic bookmark.
gatherAsk a question, collect keypresses or a spoken answer.
New · speech

Prompts repeat until the caller answers, up to play_count times. Put answers you already know in inputs and they run instantly, with no request to your server. Add input: "speech" to let callers answer out loud.

OptionTypeDescription
promptsarraysay, play or pause actions.
inputsobjectDigits → list of actions, run instantly. Up to three menus deep. Keypresses only. Not allowed with input: "speech": the whole reply is rejected.
inputstringdtmf (default), speech, or dtmf speech for either.
num_digitsintegerDigits to collect. Default 1. Keys only.
finish_on_keystringKey that ends entry. Default #. "" turns it off. Keys only.
timeoutintegerSeconds to wait for an answer after the prompts. Default 5.
play_countintegerTimes to ask, up to 10.
barge_inbooleanLet the caller cut the prompts short by pressing a key or speaking. Default true. Controls every prompt in the gather; a prompt’s own barge_in is ignored here. With false, keys and speech still count once the prompts finish.
speech_profilestringgeneral (default, most accurate) or fast (quicker results, slightly less accurate).
hintsstringWords or phrases you expect, e.g. "sales, support, billing". Up to 500 characters.
speech_timeoutintegerMilliseconds of silence that end a spoken answer. 200 to 3000, default 700.
action_on_timeout—When set, no answer sends gather.timeout to you instead of moving on.
action_urlstringWhere this gather’s result is sent. Default: your account webhook.
methodstringPOST (default) or GET.
gather · keysaction
{ "action": "gather", "num_digits": 4, "timeout": 8, "play_count": 2,
  "prompts": [
    { "action": "say", "text": "Enter your four digit code." }
  ] }
gather · speechaction
{ "action": "gather", "input": "dtmf speech", "timeout": 5,
  "hints": "sales, support, billing",
  "prompts": [
    { "action": "say", "text": "Say sales, support or billing, or press 1, 2 or 3." }
  ],
  "inputs": {
    "1": [ { "action": "redirect", "url": "/ivr/sales" } ]
  } }
Spoken answers always come to your webhook; inputs only matches keys. A gather with input: "speech" alone can’t have inputs.

What comes back: gather.completed

Sent when the caller answered and inputs didn’t already handle it.

gather.completed · keysVoitex → you
"input": { "digits": "2", "reason": "max_digits", "attempt": 1 }
gather.completed · speechVoitex → you
"input": { "digits": "", "reason": "speech", "attempt": 1,
  "speech_result": "I need to talk to support",
  "confidence": 0.81,
  "speech_request_id": "7d89b3de-f067-45ca-946e-c8f00ac3ca77" }
FieldTypeDescription
digitsstringKeys pressed. Empty for a spoken answer.
reasonstringWhy the gather ended. See below.
attemptintegerWhich time the prompts were asked.
speech_resultstringWhat the caller said. Only when reason is speech.
confidencenumber0 to 1. A hint, not a guarantee. Only when reason is speech.
speech_request_idstringID for this answer. Include it when contacting support. Only when reason is speech.
reasonMeaning
speechThe caller spoke. speech_result holds what they said.
max_digitsnum_digits keys were entered.
finish_keyKeys, then the finish key.
timeoutSome keys were entered, then the caller stopped. digits holds what they entered.

No answer: gather.timeout

Sent only when action_on_timeout is set. Otherwise the next action runs.

gather.timeoutVoitex → you
"input": { "digits": "", "reason": "timeout", "attempt": 2 }
reasonMeaning
timeoutNo answer after every prompt.
finish_keyThe finish key was pressed with nothing before it.
speech_unavailableSpeech recognition was busy. Only on input: "speech"; the prompts aren’t played.
speech_errorSpeech recognition failed during the gather. Only on input: "speech".
With input: "dtmf speech", a speech problem is never reported: the gather simply carries on with keys only, and the caller can still answer.
dialCall a number or a PBX seat.

Ring an outside number or an extension, its forward, or both at once, with your caller ID, hold music and an escape key. Every dial ends with a dial result.

OptionTypeDescription
numberstringAn outside number. Use this or extension.
extensionstringA seat on your PBX.
ringstringextension, forward or both.
ringbackstringWhat the caller hears: ring, moh or silence.
confirm—Screen the call before connecting.
escape_keystringA key the caller can press to stop waiting. Ends with escaped.
timeoutintegerSeconds to ring.
dialaction
{ "action": "dial", "extension": "101",
  "ring": "both", "ringback": "moh",
  "escape_key": "*", "timeout": 25 }
redirectFetch and run the next document.

Hand the call to another URL on your server. A redirect right after a gather is your no-input handler.

OptionTypeDescription
urlstringRelative or absolute.required
methodstringPOST or GET.
redirectaction
{ "action": "redirect", "url": "/ivr/no-input" }
recordRecord the caller, get a link.

Up to 10 minutes, with a beep and a stop key. If the caller hangs up, the audio so far is still kept and arrives with call.ended.

OptionTypeDescription
max_secondsintegerDefault 60, up to 600.
play_beepbooleanBeep before recording.
finish_on_keystring#, * or any key.
action_urlstringWhere record.completed goes.
recordactions
[ { "action": "say", "text": "Leave a message after the beep." },
  { "action": "record", "max_seconds": 120 } ]
pauseAdd a moment of silence.
OptionTypeDescription
secondsnumber0.1 to 30.required
pauseaction
{ "action": "pause", "seconds": 1.5 }
hangupEnd the call.
OptionTypeDescription
reasonstringFree text, optional. Kept in our logs only.
hangupaction
{ "action": "hangup", "reason": "menu complete" }
streamSend live call audio to your server.
New

Opens a WebSocket from Voitex to your server and streams the caller’s audio in real time. Use it to connect your own AI voice agent, speech recognition or live transcription. In connect mode the caller hears the audio you send back. In fork mode you only listen, and the call carries on with your other actions. How streams work →

OptionTypeDescription
urlstringYour WebSocket server. Must start with wss://.required
modestringconnect (default) or fork. See below.
namestringRequired for fork, unique within the call. Used by stream_stop.
trackstringWhich audio you receive: inbound (the caller, default), outbound (what the caller hears) or both, as two separate tracks. connect supports inbound only.
formatstringmulaw_8000 (default, base64 μ-law 8 kHz) or pcm16le_8000 (base64 16-bit little-endian PCM, 8 kHz). The same format is used in both directions.
parametersobjectYour own values, sent back to you in the start message. Strings only, up to 20 keys and 4 KB.
max_duration_secintegerThe stream ends after this many seconds. Default 3600. Up to 14400 (4 hours) by default; the limit can be raised for your account. To go longer, start a new stream.
ModeWhat happens
connectTwo-way. The caller talks to your server and hears what you send. The action waits until the socket closes, then stream.ended is sent to you and your reply’s actions run. Actions after a connect stream are not run.
forkListen only. The stream starts and the next action runs right away. It keeps going until stream_stop, max_duration_sec or the end of the call. Up to 2 per call.
stream · AI agentaction
{ "action": "stream",
  "url": "wss://agent.example.com/voitex",
  "mode": "connect",
  "parameters": { "customer_id": "4821" } }
stream · live transcription alongside a menuactions
[ { "action": "stream", "mode": "fork", "name": "transcript",
    "url": "wss://transcribe.example.com/voitex", "track": "both" },
  { "action": "say", "text": "Thanks for calling. How can we help?" },
  { "action": "gather", "input": "dtmf speech", "timeout": 6,
    "prompts": [ { "action": "say", "text": "Say sales or support." } ] } ]
stream can’t be used inside a gather’s prompts.
stream_stopStop a listen-only stream.
New

If that stream has already ended, nothing happens and the next action runs.

OptionTypeDescription
namestringThe name of a fork stream.required
stream_stopaction
{ "action": "stream_stop", "name": "transcript" }

Execution rules

Top to bottom

Actions run in order, and the whole reply is checked before anything plays.

Told, or asked

If you already said what happens after a gather, dial, record or player, we do it. Otherwise we ask you.

Timeouts fall through

A gather with no answer moves to the next action, so a trailing redirect is your no-input handler. Set action_on_timeout to be asked instead.

The end hangs up

Running off the end of the list ends the call. Finish with a gather, dial or redirect to carry on.

Speech goes to you

A spoken answer never runs inputs. It always comes to your webhook as gather.completed.

Streams wait, forks don’t

A connect stream holds the call until the socket closes, then asks you what’s next. A fork stream runs alongside your other actions.

Long answers

A spoken answer is cut at about 30 seconds, and the first 30 seconds are what you receive. Ask questions that need short answers.

Events

Every request includes the call, a sequence number and a timestamp, plus a block with the details for that event.

EventAddsWhen
call.started—A call comes in.
gather.completedinputKeys that inputs didn’t answer, or a spoken answer.
gather.timeoutinputA gather with action_on_timeout got no answer, a lone finish key, or a speech failure.
dial.completeddialA dial finished, answered or not.
record.completedrecordA recording finished.
player.completedplayerA player ended while the caller is still on.
redirect—A redirect action ran.
stream.endedstreamA connect stream ended while the caller is still on. See Stream events.
call.endedhangup · recordings · player · streamsThe call is over, with who ended it and why. Retried after 1, 5 and 15 seconds, and can go to a separate status callback URL.

Hangup reasons

Every call.ended has a hangup block. by says who ended the call, and reason says why.

ReasonByMeaning
caller_hangupcallerThe caller hung up.
app_hangupcustomerYour app returned a hangup action.
empty_replysystemYour app replied with no actions: an empty body or "actions": [].
actions_donesystemThe action list ended without a hangup.
webhook_errorsystemA request to your app failed. See hangup.error.
action_errorsystemAn action failed, for example a play URL returned 404. See hangup.error.
loop_guardsystem10 requests in a row with no caller input.
internal_errorsystemSomething failed on the Voitex side.
shutdownshutdownThe Voitex service restarted.
by and reason can disagree, and that’s on purpose. reason is the first cause, and once it’s set nothing changes it. If your webhook fails, the error message starts playing and the caller hangs up during it, you get by: "caller" with reason: "webhook_error" and the error object.

The error object

When reason is webhook_error or action_error, hangup.error says what went wrong.

call.endedwebhook_error
"hangup": {
  "by": "system",
  "reason": "webhook_error",
  "error": {
    "type": "http",
    "event": "gather.completed",
    "sequence": 17,
    "delivery_id": "696309d1cf7d8a88edbd61fc2346a6a6",
    "http_status": 503,
    "fallback_tried": false,
    "handled_by": "apology",
    "body_excerpt": "ngrok gateway error The server returned an invalid or incomplete HTTP response. ERR_NGROK_3004"
  }
}
FieldTypeDescription
typestringtimeout, http (a non-2xx status), invalid_json or connect (DNS, refused connection or TLS failure).
eventstringThe event of the request that failed.
sequenceintegerThe sequence of the request that failed.
delivery_idstringMatches the X-Voitex-Delivery header, so you can find the request in your own logs.
http_statusintegerThe status your server returned, or 0 when there was no response.
fallback_triedbooleantrue if your fallback URL was also tried and failed. The error then describes the fallback request, the last attempt.
handled_bystringapology (Voitex’s default message) or error_action (your on-error action).
body_excerptstringThe first 200 characters of your server’s reply, with control characters removed and whitespace collapsed. Empty if there was no body.
messagestringOnly for invalid_json and connect. For example reply is not JSON (it looks like HTML), connection refused or invalid document: action 1 (dance): unknown action "dance".
http_status, fallback_tried and body_excerpt are always present, even when they’re 0, false or empty.

When an action fails, the error names the action and what went wrong:

call.endedaction_error
"error": { "type": "action", "action": "play", "message": "fetch failed: http 404", "handled_by": "apology" }

message is a fixed description for each action, such as text-to-speech failed or the call could not be placed. For play it says what was wrong with your audio URL: fetch failed: http 404, fetch failed: timed out, fetch failed: dns: no such host or the file is not audio we can decode.

Recordings in call.ended are kept for a limited time. Download them promptly.

Dial results

Every dial.completed carries one. Branch on it to send unanswered calls to voicemail or another number.

GroupResults
connectedanswered
not answeredbusyno_answerrejecteddeclinedcanceledunavailable
caller leftescaped
could not connectinvalid_numberunroutablecongestionfailed

Signing

Each request is signed with your app’s signing secret using HMAC-SHA256 over the timestamp, a dot, and the raw body. Check it against the raw body, compare in constant time and reject old timestamps.

HeaderFormatDescription
X-Voitex-Signaturev1=hexHMAC-SHA256 of timestamp + "." + body.
X-Voitex-Timestampunix sWhen the request was sent.
X-Voitex-Call-IdstringSame as call.id.
X-Voitex-DeliverystringUnique per attempt, except a retry sent because the first attempt never reached your server (a connection failure, or ngrok ERR_NGROK_8012 / ERR_NGROK_3200), which reuses the same id. The fallback request always gets its own.
verify
import crypto from "crypto";

// Verify a Voitex webhook request
function isFromVoitex(req, secret) {
  const ts  = req.headers["x-voitex-timestamp"];
  const sig = req.headers["x-voitex-signature"].replace("v1=", "");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(ts + "." + req.rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}
import hmac, hashlib

# Verify a Voitex webhook request
def is_from_voitex(headers, raw_body: bytes, secret: str) -> bool:
    ts  = headers["X-Voitex-Timestamp"]
    sig = headers["X-Voitex-Signature"].removeprefix("v1=")
    expected = hmac.new(secret.encode(), ts.encode() + b"." + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

Timeouts & fallback

Each VoiML app has a timeout and an optional fallback URL, both set on the app in the portal. The timeout is 1 to 15 seconds, default 5.

StepWhat happens
webhookVoitex sends the request to your app’s webhook and waits up to the timeout. If your server was never reached, it’s retried once within the same timeout.
fallbackIf it times out, returns an error or sends invalid JSON, Voitex sends the same request to your fallback URL.
on-errorIf the fallback also fails, or there isn’t one, Voitex runs your app’s on-error action, if you have one.
apologyOtherwise the caller hears “We’re unable to process your call right now. Please try again later.” and the call ends.

Every event follows these rules, including stream.ended, so if your AI agent’s server goes down mid-call, your fallback can still take the caller. Apart from the one retry below, requests aren’t retried, because the caller is waiting. Return valid JSON even on your own errors.

A request that times out may still have reached your main webhook before it falls back, so the same event can arrive at both URLs. De-duplicate on call.id plus sequence.
call.ended is the exception: it’s retried after 1, 5 and 15 seconds, so recordings and bookmarks always reach you. De-duplicate on call.id plus sequence.

Automatic retry

Voitex retries a request once, after 300 ms, but only when it’s certain your app never received it.

CaseDetails
retriedA DNS failure, a refused or reset connection before the request was sent, a TLS handshake failure, or ngrok reporting it couldn’t reach your local server (ERR_NGROK_8012 or ERR_NGROK_3200).
never retriedTimeouts, ERR_NGROK_3004, any other HTTP error status, or invalid JSON. Your app may already have acted on those.
same requestThe same body and the same X-Voitex-Delivery, with a new timestamp and signature.
no extra waitThe retry happens inside the same timeout, so the caller doesn’t wait longer.
applies toRequests to your voice URL, action_urls and call.ended. Not the fallback URL request.

On-error action

A list of actions saved on your app that Voitex runs itself when your app fails, with no server needed. It’s for when you don’t run a fallback server. It runs after a webhook_error or action_error, never after loop_guard or internal_error.

To set an on-error action on your app, contact support.
on-error actionvoicemail when your server is down
[
  { "action": "say",
    "text": "Sorry, we are having a technical issue. Please leave a message after the beep." },
  { "action": "record", "max_seconds": 60 }
]
RuleWhat happens
actions1 to 10 of say, play, pause, hangup, dial and record, in the same JSON as a webhook reply. gather, redirect, player, stream and anything else that needs your server aren’t allowed.
onceIt runs at most once per call.
no webhooksNothing is sent while it runs. The only request is call.ended at the end. action_url and method on dial and record are ignored.
dialIf answered, the call ends when the far end hangs up. Busy, no answer or failed moves on to the next action, so [say, dial, say, record] works as “try the office, else take a voicemail”.
recordThe call ends when the recording finishes. The recording arrives in call.ended recordings; no record.completed is sent.
failuresIf anything fails inside the on-error action, the call hangs up with no default message.
the endWhen the list ends, the call hangs up.
invalid listIf the saved list is invalid, the default message plays instead.
call.endedShows by: "system", reason: "webhook_error" (or "action_error") and error.handled_by: "error_action".
Steps run by the on-error action are labeled “On-error” in your VoiML call logs. Pair it with a status callback URL so the voicemail recording reaches you even while your voice server is down.

Status callback URL

When your app has a status callback URL, call.ended is sent there instead of to your voice URL, with the same signature, headers and retries (right away, then after 1, 5 and 15 seconds). Every other event stays on your voice URL.

RuleDetails
https onlyThe URL must be https://.
no fallbackThe fallback URL is never used for call.ended when a status callback is set.
why use itIf your voice server is down, call.ended, including any on-error voicemail recording, still reaches you.
not setcall.ended goes to your voice URL, as before.
To set a status callback URL on your app, contact support.

Media streams

Real-time call audio over a WebSocket. Connect your own AI voice agent, speech recognition or live transcription to any call. Voitex opens the connection to you, so you only need a wss:// server. Nothing on your side has to accept phone calls.

StepWhat happens
streamYour reply includes a stream action.
connectVoitex opens a WebSocket to your url, signed with your app’s signing secret.
startWe send the call’s details and your parameters.
mediaCaller audio arrives every 20 ms. In connect mode, audio you send is played to the caller.
stopThe stream ends: the caller hung up, you closed the socket, stream_stop ran or the time limit was reached.
stream.endedconnect mode only. Sent to your webhook so you decide what happens next.

Connecting

Voitex connects from our servers to your url, so nothing on your side has to accept phone calls.

Endpoint requirements

RequirementDetails
wss://The url must start with wss://. Plain ws:// is rejected when your reply is checked.
TLS certificateA valid certificate from a public certificate authority, matching the host name. Self-signed and expired certificates are refused.
public addressThe host must resolve to a public internet address. Private, local and internal addresses are refused.
no redirectsAnswer the WebSocket upgrade directly. Redirects aren’t followed.
5 secondsAccept the connection within 5 seconds.
pingsAnswer WebSocket pings, sent every 10 seconds. Most libraries do this automatically.

A connect stream that fails any of these ends with connect_failed, and error says which one.

Headers

HeaderFormatDescription
X-Voitex-Signaturev1=hexSee Verifying.
X-Voitex-Timestampunix sWhen the connection was opened.
X-Voitex-Call-IdstringSame as call.id.
X-Voitex-Stream-IdstringUnique per stream, e.g. s_9fe98609….

Your server has 5 seconds to accept the connection. If it can’t be reached, a connect stream ends with connect_failed and you get stream.ended right away, so the caller is never left in silence. A fork stream that fails to connect is skipped, and the call carries on.

Voitex sends a WebSocket ping every 10 seconds. Most WebSocket libraries answer automatically. A connection with no answer for 30 seconds is closed.

Messages

Every message is a JSON text frame with an event name. Voitex never sends binary frames.

From Voitex

EventWhen
connectedFirst message on every stream.
startOnce, right after connected: the call and your parameters.
media20 ms of audio, about 50 per second per track.
dtmfThe caller pressed a key.
markAudio you sent before that mark has finished playing, or was cleared ("cleared": true).
stopThe stream is ending. The socket closes right after.
connectedVoitex → you
{ "event": "connected", "protocol": "voitex-stream", "version": "1.0" }
startVoitex → you
{
  "event": "start",
  "sequence": 1,
  "stream_id": "s_9fe986093bfd189d",
  "call_id": "c_8f2k41",
  "from": "+12125550187",
  "to": "+12125550100",
  "mode": "connect",
  "tracks": ["inbound"],
  "format": { "encoding": "audio/x-mulaw", "sample_rate": 8000, "channels": 1 },
  "parameters": { "customer_id": "4821" }
}

With pcm16le_8000, format is { "encoding": "audio/pcm", "endianness": "little", "sample_rate": 8000, "channels": 1 }.

mediaVoitex → you
{
  "event": "media",
  "sequence": 42,
  "stream_id": "s_9fe986093bfd189d",
  "media": {
    "track": "inbound",
    "chunk": 41,
    "timestamp": 820,
    "payload": "fn5+fn5+fn5+fn5+…"
  }
}
FieldTypeDescription
sequenceintegerOrder of every message on this stream.
media.trackstringinbound or outbound.
media.chunkintegerOrder of audio chunks on this track.
media.timestampintegerMilliseconds since the stream started.
media.payloadstringBase64 audio in the stream’s format. 20 ms is 160 bytes of μ-law, or 320 bytes of PCM.
dtmfVoitex → you
{ "event": "dtmf", "sequence": 97, "stream_id": "s_9fe986093bfd189d",
  "dtmf": { "digit": "5" } }
stopVoitex → you
{ "event": "stop", "sequence": 3110, "stream_id": "s_9fe986093bfd189d",
  "stop": { "reason": "hangup" } }
stop reasonMeaning
hangupThe caller hung up.
appYou sent stop or closed the socket.
stream_stopA stream_stop action ended this stream.
max_durationmax_duration_sec was reached.
errorSomething failed on our side.

From you

connect mode only, apart from stop. A fork stream ignores everything else.

EventWhat it does
mediaAudio to play to the caller.
markA marker in your audio. We echo it back when the audio before it has played.
clearStop playing now and drop any audio still queued.
stopEnd the stream. Closing the socket does the same.
mediayou → Voitex
{ "event": "media", "media": { "payload": "fn5+fn5+fn5+…" } }
markyou → Voitex
{ "event": "mark", "mark": { "name": "greeting-done" } }
clearyou → Voitex
{ "event": "clear" }

Playing audio

Send audio in the stream’s format, in chunks of any length. Voitex plays it in order, in real time, and buffers up to 60 seconds ahead.

Interruptions. When the caller starts talking over your agent, send clear. Playback stops within a frame and queued audio is dropped. Any marks still waiting are echoed back right away, in the order you sent them, with their original names, the same way as played marks, plus "cleared": true. A cleared mark means the caller didn’t hear the audio before it.

mark · playedVoitex → you
{ "event": "mark", "sequence": 212, "stream_id": "s_9fe986093bfd189d",
  "mark": { "name": "greeting-done" } }
mark · clearedVoitex → you
{ "event": "mark", "sequence": 240, "stream_id": "s_9fe986093bfd189d",
  "mark": { "name": "answer-2", "cleared": true } }

Knowing what was heard. Send a mark after each sentence or response. When it comes back without cleared, everything before it has played. Use it to time your next turn or to log exactly what the caller heard.

Stream events

stream.ended

Sent to your webhook when a connect stream ends while the caller is still on. Reply with actions as usual. An empty reply hangs up. It follows the same timeout and fallback rules as every other event. If the caller hung up, you get call.ended instead.

stream.endedVoitex → you
"stream": {
  "stream_id": "s_9fe986093bfd189d",
  "reason": "app_closed",
  "close_code": 1000,
  "duration_ms": 73400,
  "error": ""
}
reasonMeaning
app_closedYou sent stop or closed the socket.
connect_failedWe couldn’t connect: unreachable, refused, an endpoint requirement wasn’t met, or your account’s stream limit was reached. error says why.
max_durationmax_duration_sec was reached.
errorThe stream failed after it started.
Renewing a long stream. When stream.ended arrives with max_duration, reply with a new stream action and the caller stays on the same call.

On call.ended

call.ended lists every stream on the call, in the order they started.

call.endedVoitex → you
"streams": [
  { "stream_id": "s_9fe986093bfd189d", "name": "", "duration_ms": 73400, "reason": "app_closed" },
  { "stream_id": "s_51c2e8a07d3f2b19", "name": "transcript", "duration_ms": 91200, "reason": "hangup" }
],
"stream_ms_total": 164600

Moving a caller between streams

To hand a caller from one stream to another, say from a greeting agent to a support agent, end the first stream and start the next from your webhook.

StepWhat happens
stopSend stop on the current stream, or close the socket.
stream.endedVoitex POSTs stream.ended to your webhook, with reason: "app_closed".
streamReply with a new stream action. Voitex connects to its url and the caller carries on.
stream.ended → replyyou → Voitex
{ "actions": [
  { "action": "stream",
    "url": "wss://support-agent.example.com/voitex",
    "parameters": { "handoff_from": "greeting" } }
] }
The caller hears a short gap of silence while your webhook answers and the new socket connects, so keep your stream.ended handler fast.
If both audio sources are yours, switch inside one stream instead: keep the socket open and change which agent produces the audio on your side. There’s no gap at all.

Verifying

Each connection is signed with your app’s signing secret, the same one used for its webhooks, using HMAC-SHA256. Because there’s no body, the signature covers the timestamp, .GET, a newline, and the stream url exactly as you wrote it in the action, including any query string. Compare in constant time, and reject timestamps more than a few minutes old.

HeaderSigned string
X-Voitex-SignatureHMAC-SHA256 of X-Voitex-Timestamp + ".GET\n" + url.
verify
import crypto from "crypto";
import { WebSocketServer } from "ws";

const SECRET = process.env.VOITEX_SIGNING_SECRET; // your app’s signing secret
const STREAM_URL = "wss://agent.example.com/voitex"; // the url in your stream action

function isFromVoitex(req) {
  const ts  = req.headers["x-voitex-timestamp"] || "";
  const sig = (req.headers["x-voitex-signature"] || "").replace("v1=", "");
  const url = STREAM_URL + req.url.slice(new URL(STREAM_URL).pathname.length);
  const expected = crypto.createHmac("sha256", SECRET)
    .update(ts + ".GET\n" + url).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

const wss = new WebSocketServer({ port: 8080, verifyClient: ({ req }) => isFromVoitex(req) });

wss.on("connection", (ws) => {
  ws.on("message", (raw) => {
    const msg = JSON.parse(raw);
    if (msg.event === "start") console.log("call", msg.call_id, msg.parameters);
    if (msg.event === "media") {
      // msg.media.payload: 20 ms of caller audio. Send it to your speech engine.
    }
    if (msg.event === "dtmf") console.log("pressed", msg.dtmf.digit);
  });
  // Play audio:  ws.send(JSON.stringify({ event: "media", media: { payload } }));
  // Interrupt:   ws.send(JSON.stringify({ event: "clear" }));
});
import hmac, hashlib, time

# Verify a Voitex stream connection
def is_from_voitex(headers, url: str, secret: str) -> bool:
    ts  = headers.get("X-Voitex-Timestamp", "")
    sig = headers.get("X-Voitex-Signature", "").removeprefix("v1=")
    expected = hmac.new(secret.encode(), (ts + ".GET\n" + url).encode(),
                        hashlib.sha256).hexdigest()
    fresh = ts.isdigit() and abs(time.time() - int(ts)) < 300
    return fresh and hmac.compare_digest(sig, expected)
Behind a proxy or load balancer, rebuild the URL from the one you wrote in the action, as above, rather than from the incoming request’s host, which a proxy may change.
01

VoiML · Incoming texts

Our JSON text routing. Voitex sends each incoming text to your webhook and runs the actions you reply with. Same app, same signing secret and same JSON style as incoming calls.

How it works

A text arrives, we send it to you, you reply with an ordered list of actions. Every incoming text to the number is a new request, so you always decide what happens next.

StepWhat happens
message.receivedA text comes in. We POST you the message, you reply with actions.
runReplies are sent, in order.
redirectA redirect sends the same message to another URL on your server, which replies with actions.
gotoHands the conversation to a box in your Voitex SMS flow.
next textThe person’s next text is a new message.received, with your saved state.

Setting it up

Texts use the same VoiML app as calls. Give the app an SMS webhook, then route a number’s texts to the app.

SettingWhereDescription
SMS URLthe appWhere incoming texts are sent. Must start with https://.
SMS fallback URLthe appOptional. Tried when the SMS URL fails. Must start with https://.
signing secretthe appThe same secret as the app’s calls. See Signing.
Texts → VoiML appthe numberSends every incoming text on that number to the app.

One app can serve calls and texts, on as many numbers as you like. Use message.to.did to tell your numbers apart.

The request

Every request is a POST with a JSON body. It always carries the message, the conversation and your saved state.

POST your-app.com/voitex/smsmessage.received
{
  "version": "1.0",
  "event": "message.received",
  "sequence": 3,
  "conversation": { "id": "1730650000123" },
  "message": {
    "from":  { "number": "+12125550187", "name": "SARAH KLEIN" },
    "to":    { "did": "+12125550100" },
    "body":  "TAXI",
    "media": []
  },
  "state": { "step": "pickup" }
}
FieldTypeDescription
versionstringPayload version. Currently "1.0".
eventstringmessage.received, or redirect when a redirect action sent it.
sequenceintegerOrder of this request within the conversation. With conversation.id, use it to de-duplicate.
conversation.idstringUnique per conversation between one person and one of your numbers. Also sent as the X-Voitex-Conversation-Id header.
message.from.numberstringSender’s number, E.164.
message.from.namestringCaller ID name, when the network provides one. Otherwise null.
message.to.didstringThe number they texted.
message.bodystringThe text they sent. Can be empty when they only sent a picture.
message.mediaarrayLinks to pictures or files they sent (MMS). Empty for a plain text.
stateanyWhatever you returned last in this conversation, sent back word for word. null on the first text.

The reply

Reply 200 OK with application/json: a list of actions and, if you like, new state. The whole reply is checked before anything is sent.

200 OK · application/jsonactions
{
  "actions": [
    { "action": "reply", "text": "Where should we pick you up?" }
  ],
  "state": { "step": "pickup" }
}
FieldTypeDescription
actionsarrayOrdered list of actions. An empty list sends no reply.
stateanyOptional. Saved and sent back on the next text in this conversation.

State

Return a state object and it comes back to you, word for word, on the person’s next text. Use it for where they are in a conversation, like a booking step or an account you looked up.

You returnResult
"state": {…}Replaces the saved state.
no state keyKeeps the old state.
"state": nullClears it.

State is kept for 24 hours after the last text in the conversation.

Actions

Each item in actions is an object with an action name and its options.

ActionWhat it does
replySend a text or picture back to the person.
redirectSend the same message to another URL on your server.
gotoContinue in a box of your Voitex SMS flow.
replySend a text or picture back to the person.

Sends a text back from the number they texted. Add media to send a picture as MMS. Several reply actions send several texts, in order.

OptionTypeDescription
textstringThe message, up to 1,000 characters. Required unless you send media.
mediaarrayLinks to pictures or files to send as MMS. Must be public https:// links.
replyaction
[ { "action": "reply", "text": "Booked! Your ref is TX4821." },
  { "action": "reply", "text": "Text STATUS to check it or CANCEL to cancel." } ]
redirectSend the same message to another URL on your server.

Sends the same message to another URL on your server, which replies with actions. event is redirect on that request. Actions after a redirect are not run.

OptionTypeDescription
urlstringAbsolute https:// URL.required
redirectaction
{ "action": "redirect", "url": "https://your-app.com/sms/booking" }
gotoContinue in a box of your Voitex SMS flow.

Hands the conversation to a box in your Voitex SMS flow, by its box number. Your saved state is cleared. Actions after a goto are not run.

OptionTypeDescription
boxintegerThe box number, as shown in the portal.required
gotoaction
{ "action": "goto", "box": 5 }

Execution rules

Top to bottom

Actions run in order, and the whole reply is checked before anything is sent. One bad action, and nothing is sent.

Every text asks you

Each incoming text is its own request. Use state to remember where the person is.

Redirect and goto end the list

Anything after them is not run. Replies before them are sent first.

Empty means quiet

An empty actions list sends nothing back, but your state is still saved.

Up to 5 redirects

A chain of more than 5 redirect actions for one text stops, and nothing more is sent.

Signing

Text requests are signed exactly like call requests: HMAC-SHA256 with your app’s signing secret, over the timestamp, a dot, and the raw body. The verify code for calls works as is.

HeaderFormatDescription
X-Voitex-Signaturev1=hexHMAC-SHA256 of timestamp + "." + body.
X-Voitex-Timestampunix sWhen the request was sent.
X-Voitex-Conversation-IdstringSame as conversation.id.
X-Voitex-DeliverystringUnique per attempt.

Timeouts & fallback

Your SMS URL has 10 seconds to answer. Texts aren’t real-time like calls, but the person is still waiting for a reply.

StepWhat happens
webhookVoitex sends the request to your SMS URL and waits up to 10 seconds.
fallbackIf it times out, returns an error or sends invalid JSON, Voitex sends the same request to your SMS fallback URL.
nothingIf the fallback also fails, or there isn’t one, no reply is sent and your state is cleared.

Requests aren’t retried beyond the fallback. Return valid JSON even on your own errors.

A request that timed out may still have reached your SMS URL before the fallback, so de-duplicate on conversation.id plus sequence.

Coming from Twilio

Same idea, in JSON instead of form fields and XML.

TwilioVoiML
From · To · Bodymessage.from.number · message.to.did · message.body
MediaUrl0, MediaUrl1 …message.media
<Message>reply
<Media>media in reply
<Redirect>redirect
empty <Response/>Empty actions
cookiesstate
X-Twilio-SignatureX-Voitex-Signature
02

Notify API · Outgoing

One request sends a call or a text to one person, a list, or your whole contact list.

Send a notification

POSThttps://notify.voitexapi.com/notify/Auth-Key

Set type to SMS or CALL, pick who it reaches, and send it now or on a schedule.

FieldTypeDescription
typestringSMS or CALL.required
cidstringThe number it comes from. One of your numbers (SMS-enabled for texts). from also works.required
to · phones · labelstringWho it reaches. Exactly one. See Addressing.
titlestringA name for the broadcast, so you can find it in the portal. Default IVR Notification.
to_be_sentdatetimeYYYY-MM-DD HH:MM:SS. Schedules it. Leave it out to send right away.
dncflagDo-not-call list handling.
confirmflagConfirmation flag.

Addressing

Larger sends are queued as a broadcast you can follow in the portal.

FieldReachesDescription
toone numberSend to a single phone number.
phonesa listUp to 19 numbers are sent one by one. 20 or more go out as a broadcast.
labelcontactsComma-separated label IDs, e.g. "10,15". Reaches everyone tagged with any of them.
phone_typewith labelWhich contact phones to use: H home, M mobile, or H,M both (default).

SMS

Up to 1,000 characters, from any of your SMS-enabled numbers. Add an attachment to send it as MMS.

FieldTypeDescription
bodystringThe message, up to 1,000 characters. message also works.required
attachmentsfileA file to send as MMS. Send the request as multipart/form-data.
SMS · single numberrequest
{
  "type": "SMS",
  "cid": "2125550100",
  "to": "2125550187",
  "body": "See you tomorrow at 3 PM!"
}
SMS · labels, scheduledrequest
{
  "type": "SMS",
  "cid": "2125550100",
  "label": "10,15",
  "phone_type": "M",
  "title": "Snow day",
  "body": "School is closed today. Stay safe and warm!",
  "to_be_sent": "2026-12-08 06:30:00"
}

Calls

Choose what happens when they answer with call_type.

FieldTypeDescription
call_typestringstream or goto.required
recordingstringstream: the recording’s file name (no prefix), played when they answer.stream
sfile_idintegerstream: a Library file ID, instead of recording.
branch_numberintegergoto: the IVR box to connect them to.goto
route_numberstringgoto: the number used to bridge the call.goto
greeting · variablesJSONgoto: optional greeting and variables, as a JSON string.
CALL · streamrequest
{
  "type": "CALL",
  "cid": "2125550100",
  "to": "2125550187",
  "call_type": "stream",
  "recording": "closing_notice"
}
CALL · goto IVR boxrequest
{
  "type": "CALL",
  "cid": "2125550100",
  "to": "2125550187",
  "call_type": "goto",
  "branch_number": "5",
  "route_number": "2125550100"
}

Response

Bad numbers are reported, never silently dropped.

200 OK · application/jsonresponse
{
  "status": "success",
  "request_id": "r_51c2e8",
  "group_id": "g_20931",
  "summary": {
    "type": "SMS",
    "valid_count": 1240,
    "invalid_count": 3,
    "recipient_estimate": 1240
  },
  "invalid": {
    "212555": "invalid_format"
  },
  "errors": [],
  "warnings": []
}
FieldTypeDescription
statusstringsuccess, partial_success (some numbers were skipped), failure or error.
request_idstringUnique per request.
group_idstringIdentifies a broadcast. Smaller sends return a batch_id instead.
summaryobjectroute, type, mode, valid_count, invalid_count and recipient_estimate.
invalidobjectEvery number that was skipped, and why, e.g. invalid_format or unallocated_nanp.
errors · warningsarrayAnything that stopped or affected the send.
03

Recordings, contacts & voicemail

Manage your account’s audio, contacts and messages from your own code. Every request uses your Auth-Key header and returns status, data and errors.

Recordings

Upload audio or create speech from text in any Library album, list what is on your account, and download the audio.

EndpointMethodPurpose
/upload/POSTUpload an audio file, or create a recording from text.
/list/GETList the recordings on your account.
/file/GETDownload the audio for one recording.
Base URL: https://recording.voitexapi.com. Album numbers are listed in the portal.

Upload a recording or create one with TTS

POSThttps://recording.voitexapi.com/upload/Auth-Key

Send upload_file to upload audio, or type=tts with text to have it spoken. Send as multipart/form-data when uploading a file.

FieldTypeDescription
album_numberintegerThe album the recording goes into.required
upload_filefileThe audio, wav or mp3. Required unless type=tts.
typestringtts to create the recording from text.
textstringWith type=tts: the words to speak.
sort_numberintegerThe number callers press to pick this recording in the album. Leave it out to use the next free number.
display_namestringThe name shown for the recording in the portal.
overridestringyes deletes any recording already at this sort_number first.
Upload a filerequest
POST https://recording.voitexapi.com/upload/
Auth-Key: your_auth_key

album_number=1
sort_number=5
display_name=Holiday hours
upload_file=@holiday-hours.wav
Create with TTSrequest
POST https://recording.voitexapi.com/upload/
Auth-Key: your_auth_key

album_number=1
sort_number=15
type=tts
text=We are closed Monday for the holiday.
200 OKresponse
{
  "status": "success",
  "data": "918357",
  "errors": []
}

data is the new recording’s ID. Use it as recording_id to download the audio.

List recordings

GEThttps://recording.voitexapi.com/list/Auth-Key

Returns recordings oldest first, up to 100 at a time.

ParameterTypeDescription
limitintegerHow many to return. Default and maximum 100.
last_idintegerPaging cursor. Pass back the last_id from the previous response. Leave it out on the first request.
album_numberintegerOnly this album. Leave it out for all albums.
include_trashstringyes includes recordings in the trash. Default no.
GET /list/request
GET https://recording.voitexapi.com/list/?limit=25&album_number=1
Auth-Key: your_auth_key
200 OKresponse
{
  "status": "success",
  "data": {
    "recordings": [{
      "id": 918357,
      "album_number": 1,
      "album_name": "Announcements",
      "sort_number": 5,
      "display_name": "Holiday hours",
      "saved_datetime": "2026-08-05 14:23:11",
      "file_size": 352.23,
      "duration": "00:00:22",
      "format": "wav",
      "verify": "Y",
      "in_trash": false
    }],
    "last_id": 918357
  },
  "errors": []
}
FieldTypeDescription
idintegerThe recording ID, the same one returned by upload. Use it as recording_id.
album_number · album_name—The album and its name in the portal.
sort_numberintegerIts number in the album. Not unique: recordings that share a number play in saved_datetime order.
display_namestringIts name in the portal.
saved_datetimedatetimeWhen it was saved. When verify is D, the date it starts playing, which may be in the future.
file_size · duration—Size in KB, and length as HH:MM:SS.
formatstringThe stored audio format. Matches the Content-Type of the download.
verifystringY playable · N waiting for admin approval · D scheduled for saved_datetime.
in_trashbooleantrue if it is in the trash. Only with include_trash=yes.

Keep requesting with the returned last_id until recordings comes back empty. Recordings added while you page show up on a later page, so nothing shifts under you.

Download a recording

GEThttps://recording.voitexapi.com/file/Auth-Key

Returns the raw audio, not JSON, with a Content-Type that matches the recording’s format. If it is not found you get HTTP 404 with a JSON error, so check the status code first.

ParameterTypeDescription
recording_idintegerThe id from List recordings.required
GET /file/request
GET https://recording.voitexapi.com/file/?recording_id=918357
Auth-Key: your_auth_key
404 Not Founderror
{
  "status": "error",
  "errors": ["file not found"]
}

Contacts

POSThttps://contacts.voitexapi.com/Auth-Key

Create, update, look up and delete contacts, with their phones, fields and labels. One endpoint: pick the operation with function. A contact can have several phones and labels, and is always found by any one of its phone numbers.

functionFinds byWhat it does
create—Adds a new contact. Fails if any of its phones already belongs to a contact.
updatephoneChanges fields, phone types, phones and labels.
selectphoneReturns the contact with all its phones and labels.
deletephoneDeletes the contact with all its phones and label memberships. The labels themselves stay.

Create a contact

FieldTypeDescription
functionstringcreaterequired
phonestringOne phone, or several separated by commas.required
phone_typestringH home (default) or M mobile. Applies to every phone in the request.
first_name · last_namestringThe contact’s name.
labelintegerA label number to add the contact to.
createrequest
POST https://contacts.voitexapi.com/
Auth-Key: your_auth_key

function=create
phone=2125550187,2125550133
phone_type=M
first_name=Sarah
last_name=Klein
label=2
200 OKresponse
{
  "status": "success",
  "data": "Contact created"
}

Update a contact

phone finds the contact and must already be on it. Send only what you want to change; send a field empty to clear it. You can add one phone and remove one phone per request.

FieldTypeDescription
functionstringupdaterequired
phonestringAny phone already on the contact.required
first_name · last_name · email · notesstringContact fields.
expdateExpiration date, e.g. 2026-02-01.
field_a … field_jstringCustom fields, plus any other custom fields enabled on your account.
phone_typestringH or M. Changes the type of the phone you sent only. Other values are ignored.
add_phonestringAdds a phone. Fails if it belongs to another contact; ignored if it is already on this one.
add_phone_typestringH (default) or M for add_phone.
remove_phonestringRemoves a phone. A contact always keeps at least one; use delete to remove it entirely.
add_label · remove_labelstringLabel numbers, comma-separated, e.g. 2,3,7. Any unknown label fails the request. Removing only ends membership; the label stays.
updaterequest
POST https://contacts.voitexapi.com/
Auth-Key: your_auth_key

function=update
phone=2125550187
email=sarah@example.com
field_a=1234
add_phone=2125550164
add_phone_type=M
add_label=3,7
remove_label=5
200 OKresponse
{
  "status": "success",
  "data": "Contact updated"
}

Look up a contact

FieldTypeDescription
functionstringselectrequired
phonestringAny phone on the contact.required
selectrequest
POST https://contacts.voitexapi.com/
Auth-Key: your_auth_key

function=select
phone=2125550187
200 OKresponse
{
  "status": "success",
  "data": {
    "contact": {
      "first_name": "Sarah", "last_name": "Klein",
      "email": "sarah@example.com", "notes": "", "exp": null,
      "address": "", "city": "", "state": "", "zip": "",
      "field_a": "1234", "field_b": "", "field_j": ""
    },
    "phones": [
      { "phone": "2125550187", "type": "M" },
      { "phone": "2125550164", "type": "M" }
    ],
    "labels": [2, 3, 7]
  }
}

Delete a contact

Removes the whole contact. To remove just one number, use update with remove_phone.

deleterequest
POST https://contacts.voitexapi.com/
Auth-Key: your_auth_key

function=delete
phone=2125550187
Errorresponse
{
  "status": "error",
  "errors": ["No contact found for phone: 2125550187"]
}

Voicemail

Pull new voicemails and download the audio into your CRM, ticketing or inbox. Both endpoints are GET with query parameters.

List voicemails

GEThttps://vm.voitexapi.com/messages/Auth-Key

Returns messages oldest first, up to 100 at a time.

ParameterTypeDescription
limitintegerHow many to return. Default and maximum 100.
last_idintegerPaging cursor. Pass back the last_id from the previous response to get only newer messages.
vm_group_idintegerOnly this voicemail box. Leave it out for all boxes.
GET /messages/request
GET https://vm.voitexapi.com/messages/?limit=25&last_id=4180
Auth-Key: your_auth_key
200 OKresponse
{
  "status": "success",
  "data": {
    "voice_mails": [{
      "id": 4181,
      "vm_group_id": 3,
      "call_id": "AST10-1689867312.264",
      "file_name": "vm_4181_1754500991",
      "clid": "2125550142",
      "date": "2026-10-27 10:42:05"
    }],
    "last_id": 4181
  }
}
FieldTypeDescription
idintegerThe voicemail ID. Use it as vm_id to download the audio.
vm_group_idintegerThe box it was left in.
call_idstringThe call’s ID, to match against your call logs.
file_namestringInternal file name, for reference only.
clidstringThe caller ID of whoever left it.
datedatetimeWhen it was left, YYYY-MM-DD HH:MM:SS.

Store the last last_id you received and send it next time to fetch only new voicemails.

Download a voicemail

GEThttps://vm.voitexapi.com/file/Auth-Key

Returns the raw WAV audio (audio/x-wav), not JSON. If it is not found you get HTTP 404 with a JSON error.

ParameterTypeDescription
vm_idintegerThe id from List voicemails.required
GET /file/request
GET https://vm.voitexapi.com/file/?vm_id=4181
Auth-Key: your_auth_key

Send SMS

POSThttps://sms.voitexapi.com/send/Auth-Key

A simple one-to-one text from one of your SMS-enabled numbers. For lists, labels, MMS or scheduling, use the Notify API.

FieldTypeDescription
fromstringYour SMS-enabled number.required
tostringThe number to text.required
bodystringThe message.required
POST /send/request
POST https://sms.voitexapi.com/send/
Auth-Key: your_auth_key

from=2125550100
to=2125550187
body=Your appointment is confirmed.
200 OKresponse
{
  "status": "success",
  "data": {
    "from": "2125550100",
    "to": "2125550187",
    "body": "Your appointment is confirmed.",
    "did_type": "TN",
    "referenceID": "u7T0um"
  },
  "errors": []
}

did_type is TN for a local number or TF for toll-free.

04

Grouply API

Manage your Grouply text groups from your own system: invite and remove members, message the whole group, and list who is in it.

Overview

POSThttps://grouply.voitexapi.com/Auth-Key

One endpoint: pick the action with function. group is the group’s phone number and must be a Grouply group on your account.

FieldTypeDescription
functionstringadd_member, remove_member, send or list_members.required
groupstringThe group’s phone number.required
request_idstringYour own ID for the request, up to 64 letters, digits and . _ : -. Repeating a request with the same ID never runs it twice, so retries are safe.
Members are invited, not added. Each person joins only after replying YES to the invite text, or pressing 1 on the invite call. API messages follow the same rules as an admin’s: member limit, quiet hours, message length and the daily sending limit. Grouply messages are priced like standard messaging; ask support@voitex.com about volume discounts.

Add a member

Sends an invite. A number that was removed earlier is invited again.

FieldTypeDescription
phonestringThe member’s phone number.required
namestringShown to the group, e.g. “Sarah Klein has joined the group”. Up to 50 characters; cannot end with CALL or CONFIRM.
typestringsms (default) gets texts. call gets each message as a phone call, for landlines; the invite is a call too.
confirminteger1 accepts the per-message overage charge when the group is at its member limit. Without it, adding to a full group fails.
add_memberrequest
POST https://grouply.voitexapi.com/
Auth-Key: your_auth_key

function=add_member
group=2125550199
phone=2125550187
name=Sarah Klein
type=sms
request_id=add-1042
200 OKresponse
{
  "status": "success",
  "errors": "",
  "data": {
    "phone": "2125550187",
    "status": "invited",
    "type": "sms",
    "message": "Invite sent to 2125550187. They will be added once they accept."
  }
}

Remove a member

They stop receiving group messages right away.

remove_memberrequest
POST https://grouply.voitexapi.com/
Auth-Key: your_auth_key

function=remove_member
group=2125550199
phone=2125550187
request_id=rem-1042
200 OKresponse
{
  "status": "success",
  "errors": "",
  "data": {
    "phone": "2125550187",
    "status": "removed",
    "type": "sms",
    "message": "2125550187 has been removed from the group."
  }
}

Send to the group

Goes to every active member from the group’s number, shown as coming from the group’s admin. Text members get a text; call members get a phone call.

FieldTypeDescription
messagestringThe text. Cannot start with #, which is reserved for commands.required
sendrequest
POST https://grouply.voitexapi.com/
Auth-Key: your_auth_key

function=send
group=2125550199
message=Practice is canceled tonight.
request_id=msg-7781
200 OKresponse
{
  "status": "success",
  "errors": "",
  "data": {
    "recipients": 42,
    "scheduled_for": null,
    "message": "Message sent."
  }
}

recipients is how many members it went to. scheduled_for is when it will go out if the group’s quiet hours held it, or null if it was sent right away.

List members

list_membersrequest
POST https://grouply.voitexapi.com/
Auth-Key: your_auth_key

function=list_members
group=2125550199
200 OKresponse
{
  "status": "success",
  "errors": "",
  "data": {
    "members": [
      { "phone": "2125550187", "name": "Sarah Klein",
        "status": "active", "type": "sms", "is_admin": false },
      { "phone": "2125550176", "name": "Jane Roe",
        "status": "invited", "type": "call", "is_admin": false }
    ]
  }
}
statusReceivesMeaning
invitednoWaiting for the person to confirm.
activeyesA member of the group.
leftnoThe person left the group.
removednoRemoved by an admin or the API.

Errors

Errors return "status": "error" with a list of messages: invalid or missing group number, group not found, invalid or missing phone, type must be sms or call, message is empty, messages starting with # are not allowed, the member is already in the group, and this group is currently full. grouply service unavailable, please try again means nothing was done; repeat the request with the same request_id.

05

Reference

Limits at a glance, and the questions we hear most.

Limits

LimitValue
webhook timeout1 to 15 seconds per app, default 5, with one retry after 300 ms if your server was never reached, then the fallback URL if set (call.ended is also retried: 1, 5, 15 s)
on-error action1 to 10 actions, run once per call
on-error fieldssay text 1,000 characters, play URL 2,048 characters, dial numbers in E.164, dial timeout 5 to 120 s, hangup reason 100 characters
instant inputs3 menus deep per reply
gather.play_countUp to 10
gather.hints500 characters
gather.speech_timeout200 to 3000 ms, default 700
spoken answer30 seconds; longer answers are cut
speech languagesEnglish
play.loopUp to 10
player file3 hours, 120 MB
player.pause_timeout5 to 3600 s, default 300
player seek1 to 3600 s per press
player menus2 levels deep
record.max_secondsUp to 600, default 60
pause.seconds0.1 to 30
say.speed0.5 to 2.0
stream connect5 seconds
stream.max_duration_secDefault 3,600. Up to 14,400 (4 hours) by default; can be raised for your account
fork streams2 per call
streams per account20 at once by default; can be raised on request
stream.parameters20 keys, 4 KB
stream audio8 kHz, μ-law or 16-bit PCM, 20 ms frames
stream playback buffer60 seconds
SMS webhook timeout10 seconds, then the SMS fallback URL if set
reply.text1,000 characters
SMS redirects5 per incoming text
SMS stateKept 24 hours after the last text
SMS body1,000 characters
phonesUp to 19 sent one by one; 20+ as a broadcast
list limit100 recordings or voicemails per request
Grouply name50 characters
request_id64 characters

Questions

What happens if my server is slow or down?

Each reply must arrive within your app’s timeout (1 to 15 seconds, default 5), and the caller hears silence while you think. If your webhook fails, Voitex sends the same request to your app’s fallback URL. If that also fails, Voitex runs your app’s on-error action if you have one, such as taking a voicemail; otherwise the caller hears a short apology and the call ends. call.ended tells you which request failed and why in hangup.error. Set a fallback or an on-error action on every app you use in production.

Will I ever get the same event twice?

Yes, in three cases: a request that never reached your server is retried once with the same X-Voitex-Delivery, call.ended is retried after 1, 5 and 15 seconds if your server does not answer, and a request that timed out at your webhook may have reached it before going to your fallback URL. De-duplicate on call.id plus sequence.

How do I tell my numbers apart?

Use call.to.did, the number the caller dialed. One webhook can serve every number on your account.

Which audio formats work?

mp3, wav, ogg, flac, aiff and more. Files are converted for the phone line automatically, so a high-quality file sounds the same as a small one.

Which languages can callers speak?

English for now.

How should I collect phone or account numbers?

With keypresses. People pause between groups of digits, so a spoken number can arrive in pieces.

How should I handle spoken menu choices?

Look for the words you expect in speech_result rather than requiring an exact match, and re-prompt if none are found. Use confidence as a hint only.

What if speech recognition is down?

Use dtmf speech and callers can always press a key instead. With input: "speech" alone, set action_on_timeout or end with a redirect so a failure reaches you.

Do I need to accept connections from Voitex’s IP addresses?

Yes, if you filter by IP. Voitex connects to you, so your server only needs to accept incoming wss:// connections. Verify the signature instead of relying on IP filtering alone.

Which audio format should I use for streams?

mulaw_8000 if your speech engine or AI accepts μ-law (most do, and it’s what phone calls carry). pcm16le_8000 if it needs raw PCM. Phone audio is 8 kHz either way, so higher sample rates add nothing.

How do I let callers interrupt my AI agent?

When your speech engine detects the caller talking, send clear. Playback stops immediately.

What happens if my stream server goes down mid-call?

The stream ends with error and you get stream.ended, so your webhook can apologize, transfer the call or start a new stream. If your webhook is down too, it goes to your fallback URL.

What do the VoiML call logs show?

Every request Voitex sent your app and what came back, with timings, status and headers, each action that ran, and how the call ended: hangup.by, hangup.reason and hangup.error. A retry that reused the same X-Voitex-Delivery is marked, and steps run by your on-error action are labeled “On-error”. Every record step shows the recording link and duration, even with “log request/response bodies” turned off. That setting hides bodies and action JSON, but not recording links.

Can I see what happened on a stream?

Yes. Your VoiML call logs in the portal show each stream’s connection, start, keypresses, marks, clear and how it ended, plus how long the first audio took in each direction. Audio itself is never logged.

Can one app handle calls and texts?

Yes. Set both the voice URL and the SMS URL on the app, and route the number’s calls and texts to it.

How do I know which number they texted?

Use message.to.did. One SMS URL can serve every number on your account.

What if they text only a picture?

message.body is empty and message.media has the links.

Do I have to store bookmarks?

Yes. Voitex reports positions; bookmarks, likes, playlists and listening history are yours to keep in your own system.