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.
The two directions, your Auth-Key and your app’s signing secret. Read this first, then pick an API below.
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.
Everything is HTTPS. Voitex sends your webhook JSON; you send Voitex form fields and get JSON back. There are no SDKs to install.
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.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.
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 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.
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/Our JSON call routing. Voitex sends each incoming call to your webhook and runs the actions you reply with.
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.
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.Every request is a POST with a JSON body. It always carries the call and your saved state, plus the details for that event.
{
"version": "1.0",
"event": "call.started",
"call": {
"id": "c_8f2k41",
"from": { "number": "+12125550187", "name": "SARAH KLEIN" },
"to": { "did": "+12125550100" }
},
"state": null
}versionstringPayload version. Currently "1.0".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.Reply 200 OK with application/json: a list of actions and, if you like, new state. The whole reply is checked before anything plays.
{
"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" }
}stateanyOptional. Saved and sent back on every later request for this call.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.
"state": {…}Replaces the saved state.no state keyKeeps the old state."state": nullClears it.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.
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.Each item in actions is an object with an action name and its options. Mix them in any order.
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.
textstringWhat to say.requiredvoicestringOverride the account voice.languagestringDefault en-US.speednumber0.5 to 2.0.barge_inbooleanLet a keypress cut it short.{ "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.
urlstringThe audio file.requiredloopintegerRepeat up to 10 times.barge_inbooleanLet a keypress cut it short.{ "action": "play", "url": "https://cdn.example.com/greeting.mp3" }playerLong audio callers can move around in.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 →
urlstringThe audio file.requiredstart_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.Use these in controls, in paused_controls and inside menus.
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.{
"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"
}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.
{
"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
}
}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.call.ended brings their position as an automatic bookmark.gatherAsk a question, collect keypresses or a spoken answer.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.
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.{ "action": "gather", "num_digits": 4, "timeout": 8, "play_count": 2,
"prompts": [
{ "action": "say", "text": "Enter your four digit code." }
] }{ "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" } ]
} }inputs only matches keys. A gather with input: "speech" alone can’t have inputs.gather.completedSent when the caller answered and inputs didn’t already handle it.
"input": { "digits": "2", "reason": "max_digits", "attempt": 1 }"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" }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.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.gather.timeoutSent only when action_on_timeout is set. Otherwise the next action runs.
"input": { "digits": "", "reason": "timeout", "attempt": 2 }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".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.
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.{ "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.
urlstringRelative or absolute.requiredmethodstringPOST or GET.{ "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.
max_secondsintegerDefault 60, up to 600.play_beepbooleanBeep before recording.finish_on_keystring#, * or any key.action_urlstringWhere record.completed goes.[ { "action": "say", "text": "Leave a message after the beep." },
{ "action": "record", "max_seconds": 120 } ]pauseAdd a moment of silence.secondsnumber0.1 to 30.required{ "action": "pause", "seconds": 1.5 }hangupEnd the call.reasonstringFree text, optional. Kept in our logs only.{ "action": "hangup", "reason": "menu complete" }streamSend live call audio to your server.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 →
urlstringYour WebSocket server. Must start with wss://.requiredmodestringconnect (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.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.{ "action": "stream",
"url": "wss://agent.example.com/voitex",
"mode": "connect",
"parameters": { "customer_id": "4821" } }[ { "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.If that stream has already ended, nothing happens and the next action runs.
namestringThe name of a fork stream.required{ "action": "stream_stop", "name": "transcript" }Actions run in order, and the whole reply is checked before anything plays.
If you already said what happens after a gather, dial, record or player, we do it. Otherwise we ask you.
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.
Running off the end of the list ends the call. Finish with a gather, dial or redirect to carry on.
A spoken answer never runs inputs. It always comes to your webhook as gather.completed.
A connect stream holds the call until the socket closes, then asks you what’s next. A fork stream runs alongside your other actions.
A spoken answer is cut at about 30 seconds, and the first 30 seconds are what you receive. Ask questions that need short answers.
Every request includes the call, a sequence number and a timestamp, plus a block with the details for that event.
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.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.Every call.ended has a hangup block. by says who ended the call, and reason says why.
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.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.When reason is webhook_error or action_error, hangup.error says what went wrong.
"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"
}
}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.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:
"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.
call.ended are kept for a limited time. Download them promptly.Every dial.completed carries one. Branch on it to send unanswered calls to voicemail or another number.
connectedanswerednot answeredbusyno_answerrejecteddeclinedcanceledunavailablecaller leftescapedcould not connectinvalid_numberunroutablecongestionfailedEach 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.
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.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)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.
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.
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.Voitex retries a request once, after 300 ms, but only when it’s certain your app never received it.
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.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.
[
{ "action": "say",
"text": "Sorry, we are having a technical issue. Please leave a message after the beep." },
{ "action": "record", "max_seconds": 60 }
]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".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.
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.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.
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.Voitex connects from our servers to your url, so nothing on your side has to accept phone calls.
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.
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.
Every message is a JSON text frame with an event name. Voitex never sends binary frames.
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.{ "event": "connected", "protocol": "voitex-stream", "version": "1.0" }{
"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 }.
{
"event": "media",
"sequence": 42,
"stream_id": "s_9fe986093bfd189d",
"media": {
"track": "inbound",
"chunk": 41,
"timestamp": 820,
"payload": "fn5+fn5+fn5+fn5+…"
}
}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.{ "event": "dtmf", "sequence": 97, "stream_id": "s_9fe986093bfd189d",
"dtmf": { "digit": "5" } }{ "event": "stop", "sequence": 3110, "stream_id": "s_9fe986093bfd189d",
"stop": { "reason": "hangup" } }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.connect mode only, apart from stop. A fork stream ignores everything else.
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.{ "event": "media", "media": { "payload": "fn5+fn5+fn5+…" } }{ "event": "mark", "mark": { "name": "greeting-done" } }{ "event": "clear" }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.
{ "event": "mark", "sequence": 212, "stream_id": "s_9fe986093bfd189d",
"mark": { "name": "greeting-done" } }{ "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.endedSent 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": {
"stream_id": "s_9fe986093bfd189d",
"reason": "app_closed",
"close_code": 1000,
"duration_ms": 73400,
"error": ""
}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.stream.ended arrives with max_duration, reply with a new stream action and the caller stays on the same call.call.endedcall.ended lists every stream on the call, in the order they started.
"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": 164600To 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.
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.{ "actions": [
{ "action": "stream",
"url": "wss://support-agent.example.com/voitex",
"parameters": { "handoff_from": "greeting" } }
] }stream.ended handler fast.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.
X-Voitex-SignatureHMAC-SHA256 of X-Voitex-Timestamp + ".GET\n" + url.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)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.
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.
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.Texts use the same VoiML app as calls. Give the app an SMS webhook, then route a number’s texts to the app.
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://.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.
Every request is a POST with a JSON body. It always carries the message, the conversation and your saved state.
{
"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" }
}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.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.
{
"actions": [
{ "action": "reply", "text": "Where should we pick you up?" }
],
"state": { "step": "pickup" }
}stateanyOptional. Saved and sent back on the next text in this conversation.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.
"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.
Each item in actions is an object with an action name and its options.
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.
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.[ { "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.
urlstringAbsolute https:// URL.required{ "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.
boxintegerThe box number, as shown in the portal.required{ "action": "goto", "box": 5 }Actions run in order, and the whole reply is checked before anything is sent. One bad action, and nothing is sent.
Each incoming text is its own request. Use state to remember where the person is.
Anything after them is not run. Replies before them are sent first.
An empty actions list sends nothing back, but your state is still saved.
A chain of more than 5 redirect actions for one text stops, and nothing more is sent.
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.
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.Your SMS URL has 10 seconds to answer. Texts aren’t real-time like calls, but the person is still waiting for a reply.
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.
conversation.id plus sequence.Same idea, in JSON instead of form fields and XML.
From · To · Bodymessage.from.number · message.to.did · message.bodyMediaUrl0, MediaUrl1 …message.media<Message>reply<Media>media in reply<Redirect>redirectempty <Response/>Empty actionscookiesstateX-Twilio-SignatureX-Voitex-SignatureOne request sends a call or a text to one person, a list, or your whole contact list.
Set type to SMS or CALL, pick who it reaches, and send it now or on a schedule.
typestringSMS or CALL.requiredcidstringThe number it comes from. One of your numbers (SMS-enabled for texts). from also works.requiredtitlestringA 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.Larger sends are queued as a broadcast you can follow in the portal.
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).Up to 1,000 characters, from any of your SMS-enabled numbers. Add an attachment to send it as MMS.
bodystringThe message, up to 1,000 characters. message also works.requiredattachmentsfileA file to send as MMS. Send the request as multipart/form-data.{
"type": "SMS",
"cid": "2125550100",
"to": "2125550187",
"body": "See you tomorrow at 3 PM!"
}{
"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"
}Choose what happens when they answer with call_type.
call_typestringstream or goto.requiredrecordingstringstream: the recording’s file name (no prefix), played when they answer.streamsfile_idintegerstream: a Library file ID, instead of recording.branch_numberintegergoto: the IVR box to connect them to.gotoroute_numberstringgoto: the number used to bridge the call.gotogreeting · variablesJSONgoto: optional greeting and variables, as a JSON string.{
"type": "CALL",
"cid": "2125550100",
"to": "2125550187",
"call_type": "stream",
"recording": "closing_notice"
}{
"type": "CALL",
"cid": "2125550100",
"to": "2125550187",
"call_type": "goto",
"branch_number": "5",
"route_number": "2125550100"
}Bad numbers are reported, never silently dropped.
{
"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": []
}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.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.
Upload audio or create speech from text in any Library album, list what is on your account, and download the audio.
/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.https://recording.voitexapi.com. Album numbers are listed in the portal.Send upload_file to upload audio, or type=tts with text to have it spoken. Send as multipart/form-data when uploading a file.
album_numberintegerThe album the recording goes into.requiredupload_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.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
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.
{
"status": "success",
"data": "918357",
"errors": []
}data is the new recording’s ID. Use it as recording_id to download the audio.
Returns recordings oldest first, up to 100 at a time.
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 https://recording.voitexapi.com/list/?limit=25&album_number=1 Auth-Key: your_auth_key
{
"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": []
}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.
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.
recording_idintegerThe id from List recordings.requiredGET https://recording.voitexapi.com/file/?recording_id=918357 Auth-Key: your_auth_key
{
"status": "error",
"errors": ["file not found"]
}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.
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.functionstringcreaterequiredphonestringOne phone, or several separated by commas.requiredphone_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.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
{
"status": "success",
"data": "Contact created"
}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.
functionstringupdaterequiredphonestringAny phone already on the contact.requiredfirst_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.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
{
"status": "success",
"data": "Contact updated"
}functionstringselectrequiredphonestringAny phone on the contact.requiredPOST https://contacts.voitexapi.com/ Auth-Key: your_auth_key function=select phone=2125550187
{
"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]
}
}Removes the whole contact. To remove just one number, use update with remove_phone.
POST https://contacts.voitexapi.com/ Auth-Key: your_auth_key function=delete phone=2125550187
{
"status": "error",
"errors": ["No contact found for phone: 2125550187"]
}Pull new voicemails and download the audio into your CRM, ticketing or inbox. Both endpoints are GET with query parameters.
Returns messages oldest first, up to 100 at a time.
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 https://vm.voitexapi.com/messages/?limit=25&last_id=4180 Auth-Key: your_auth_key
{
"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
}
}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.
Returns the raw WAV audio (audio/x-wav), not JSON. If it is not found you get HTTP 404 with a JSON error.
vm_idintegerThe id from List voicemails.requiredGET https://vm.voitexapi.com/file/?vm_id=4181 Auth-Key: your_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.
fromstringYour SMS-enabled number.requiredtostringThe number to text.requiredbodystringThe message.requiredPOST https://sms.voitexapi.com/send/ Auth-Key: your_auth_key from=2125550100 to=2125550187 body=Your appointment is confirmed.
{
"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.
Manage your Grouply text groups from your own system: invite and remove members, message the whole group, and list who is in it.
One endpoint: pick the action with function. group is the group’s phone number and must be a Grouply group on your account.
functionstringadd_member, remove_member, send or list_members.requiredgroupstringThe group’s phone number.requiredrequest_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.Sends an invite. A number that was removed earlier is invited again.
phonestringThe member’s phone number.requirednamestringShown 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.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
{
"status": "success",
"errors": "",
"data": {
"phone": "2125550187",
"status": "invited",
"type": "sms",
"message": "Invite sent to 2125550187. They will be added once they accept."
}
}They stop receiving group messages right away.
POST https://grouply.voitexapi.com/ Auth-Key: your_auth_key function=remove_member group=2125550199 phone=2125550187 request_id=rem-1042
{
"status": "success",
"errors": "",
"data": {
"phone": "2125550187",
"status": "removed",
"type": "sms",
"message": "2125550187 has been removed from 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.
messagestringThe text. Cannot start with #, which is reserved for commands.requiredPOST https://grouply.voitexapi.com/ Auth-Key: your_auth_key function=send group=2125550199 message=Practice is canceled tonight. request_id=msg-7781
{
"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.
POST https://grouply.voitexapi.com/ Auth-Key: your_auth_key function=list_members group=2125550199
{
"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 }
]
}
}invitednoWaiting for the person to confirm.activeyesA member of the group.leftnoThe person left the group.removednoRemoved by an admin or the API.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.
Limits at a glance, and the questions we hear most.
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 callon-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 charactersinstant inputs3 menus deep per replygather.play_countUp to 10gather.hints500 charactersgather.speech_timeout200 to 3000 ms, default 700spoken answer30 seconds; longer answers are cutspeech languagesEnglishplay.loopUp to 10player file3 hours, 120 MBplayer.pause_timeout5 to 3600 s, default 300player seek1 to 3600 s per pressplayer menus2 levels deeprecord.max_secondsUp to 600, default 60pause.seconds0.1 to 30say.speed0.5 to 2.0stream connect5 secondsstream.max_duration_secDefault 3,600. Up to 14,400 (4 hours) by default; can be raised for your accountfork streams2 per callstreams per account20 at once by default; can be raised on requeststream.parameters20 keys, 4 KBstream audio8 kHz, μ-law or 16-bit PCM, 20 ms framesstream playback buffer60 secondsSMS webhook timeout10 seconds, then the SMS fallback URL if setreply.text1,000 charactersSMS redirects5 per incoming textSMS stateKept 24 hours after the last textSMS body1,000 charactersphonesUp to 19 sent one by one; 20+ as a broadcastlist limit100 recordings or voicemails per requestGrouply name50 charactersrequest_id64 charactersEach 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.
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.
Use call.to.did, the number the caller dialed. One webhook can serve every number on your account.
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.
English for now.
With keypresses. People pause between groups of digits, so a spoken number can arrive in pieces.
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.
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.
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.
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.
When your speech engine detects the caller talking, send clear. Playback stops immediately.
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.
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.
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.
Yes. Set both the voice URL and the SMS URL on the app, and route the number’s calls and texts to it.
Use message.to.did. One SMS URL can serve every number on your account.
message.body is empty and message.media has the links.
Yes. Voitex reports positions; bookmarks, likes, playlists and listening history are yours to keep in your own system.