SMS Call Flows (Voice) API
A call flow is what a caller hears: the number answers, speaks a greeting, offers a keypad menu, forwards the call somewhere, takes a voicemail, hangs up. It is the voice counterpart of Flows, which are text conversations.
Everything the builder can do, this API can do — the same definition format and the same
validator — so a flow your platform builds opens and edits normally in the browser, and one
built in the browser round-trips through GET → PATCH unchanged.
Building one by hand is done on sms.bodek.us → Call flows (and in the Bodek SMS app on the phone). This page is the API and webhook reference.
Base https://sms.bodek.us/api/v1
Auth Authorization: Bearer bs_live_…
Scopes voice:read list call flows, answered calls and recordings
voice:write create, change, activate, pause and delete call flows
Call flows need a number dedicated to your account; the shared sending pool cannot host one.
⚠ Every answered call is announced
The first thing a caller hears on every answered call is the recording announcement — before the greeting, before any menu, before anything else. The default wording is:
This call is being recorded.
You can change the wording with announce. You cannot switch
it off. Sending "announce": "" does not disable it — it restores the
default sentence. This is enforced in the engine, not in this document: the announcement is
emitted before the flow's first step runs, and no step can record audio until it has played.
A recording that reaches the platform for a call with no announcement on record is
rejected and discarded.
Why it is built this way: in all-party-consent jurisdictions an up-front announcement is what makes recording a call lawful, and the announcement is worthless if it can be skipped for some calls. Making it an invariant means neither a flow, nor a mistake, nor a misbehaving device can produce a recording nobody was told about.
Your responsibility. The announcement is a platform guarantee
about what the caller is told; it is not legal advice and it is not a complete compliance
programme. Consent law varies by state and by country, and some jurisdictions require more
than an announcement for some purposes. Choose wording that is accurate for what you actually
do with the audio, keep retain_days no longer than you need, and take your own
advice on the rules that apply to your calls.
Every answered call records what was announced and when. It is on the call object
(consent), on every recording made during it (announcement), on the
call.consent webhook, and in the X-Bodek-Announcement header when you
download the audio. Nothing can be recorded without that trail.
Recording behaviour is set per flow with record_mode:
| Value | Meaning |
|---|---|
steps default |
Announce every call; write audio only for steps that record (voicemail,
record). Smallest storage and liability footprint. |
all | Announce and record the whole call. |
off | Never write audio. The announcement still plays. |
retain_days (1–3650, default 90) is when recordings are purged automatically.
What a number can actually do
This is the part that makes voice different from everything else in the API, and it is worth understanding before you design a flow.
Calls are answered by the Android phone that holds the number, and stock Android gives an app no access to call audio: it cannot inject sound into a call, cannot capture call audio, has no API for "the caller pressed a key", and cannot transfer a connected call. Some phones, with extra setup, can do some of it. So each number reports what it can really do and the platform fits the flow to it.
| Primitive | Needed by | If the number cannot do it |
|---|---|---|
play | every step that speaks | the call is answered in silence — check this first |
gather | menu, ask |
the prompt is read out, then the step's fallback is taken |
dial_transfer | forward |
on_fail is taken (usually voicemail) |
dial_bridge | bridge | as above |
record | voicemail, record |
a short apology is spoken and the flow continues |
sms | sms, notify |
always available — the platform sends these, not the phone |
Every flow you read back carries two fields that tell you exactly where you stand:
"needs": ["play", "gather", "dial_transfer", "record"],
"unsupported": ["gather", "dial_transfer", "record"]
needs is what the definition requires; unsupported is the subset the
answering number cannot do today. An unsupported list is not an error and
does not stop a flow — the call still happens, in reduced form. Design for that: give every
menu a fallback and every forward an
on_fail, and a flow stays useful on a limited number and gets richer, with no
edit, when the number gains capability.
To watch it happen in production, subscribe to call.unsupported; it fires with the
step and the exact primitive that was missing.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /v1/calls/flows | your call flows (?expand=definition for the steps) |
| POST | /v1/calls/flows | create one (optionally active, with a full definition) |
| GET | /v1/calls/flows/templates | starter definitions to build from |
| GET | /v1/calls/flows/schema | every step type and its fields, for building your own editor |
| POST | /v1/calls/flows/validate | check a definition without storing it |
| GET | /v1/calls/flows/{id} | one flow with its definition, errors and warnings |
| PATCH | /v1/calls/flows/{id} | change any subset of the fields |
| PUT | /v1/calls/flows/{id} | replace it — fields you omit go back to their defaults |
| DELETE | /v1/calls/flows/{id} | delete it; calls it already handled keep their history |
| POST | /v1/calls/flows/{id}/activate | switch it on (refused while it has errors) |
| POST | /v1/calls/flows/{id}/pause | switch it off |
| POST | /v1/calls/flows/{id}/rotate_secret | new signing secret for its API steps |
| GET | /v1/calls/voice | answered calls that ran a flow |
| GET | /v1/calls/voice/{id} | one call, with its log and recordings |
| GET | /v1/calls/voice/{id}/log | its step-by-step history |
| GET | /v1/calls/recordings | recordings you can download |
| GET | /v1/calls/recordings/{id} | the audio (add ?meta=1 for metadata only) |
Ids are opaque and stable: vf_… a flow, vc_… a call,
vr_… a recording.
Flow fields
number_id | required on create — which of your numbers answers |
name | up to 120 characters |
active | switched on. A flow with definition errors is forced inactive |
callers | any · hidden · list · not_list · members · not_members |
caller_list | E.164 numbers, or prefixes ending in * (e.g. +1800*), up to 500 |
priority | −100…100, highest wins when several flows match a call |
tz | IANA zone for hours steps and {{time}} |
announce | the announcement wording. Empty restores the default — it cannot be switched off |
record_mode | steps · all · off |
retain_days | 1–3650, default 90 |
voice_name | preferred speaking voice (a hint — the number picks the closest it has) |
voice_rate | speaking speed, 50–200 (percent) |
max_call_s | longest a call may run, 30–3600 (default 1800) |
holidays | dates every holiday step falls back to |
definition | {"start": …, "steps": {…}} — see below |
When several active flows could answer a call, the highest priority whose
callers filter matches wins. A withheld number only matches
hidden, not_list and not_members, because there is no
number to compare. If no flow matches, the call is left to the number's ordinary call rules.
The definition format
{
"start": "greet",
"steps": {
"greet": {"type": "menu", "text": "Thanks for calling.",
"options": [{"key": "1", "label": "sales", "next": "sales"},
{"key": "2", "label": "to leave a message", "next": "vm"}],
"retries": 2, "timeout_s": 7, "fallback": "vm"},
"sales": {"type": "forward", "to": "+15551234567",
"announce": "Connecting you to sales.", "on_fail": "vm"},
"vm": {"type": "voicemail", "text": "Please leave a message after the tone.",
"max_s": 120, "next": "bye"},
"bye": {"type": "hangup", "text": "Thanks, goodbye."}
}
}
Step ids are your own: letters, digits and _, up to 40 characters. Every link
(next, fallback, on_fail, else, a menu
option's next) is a step id, or empty to end the call.
Saving normalises the definition: unknown fields are dropped, numbers are clamped into range, and a link pointing at a step that does not exist is reported as an error and stored as empty. So read the definition back after saving if you keep your own copy — and note the consequence: because a dangling link is cleared on the way in, the stored flow may be valid even though the save reported an error about what you sent.
Step reference
say
Speak, then continue. text (required, up to 1000 chars), next.
menu
Speak a prompt and wait for one keypress.
{"type": "menu", "text": "Thanks for calling.",
"options": [{"key": "1", "label": "sales", "next": "sales"}],
"show_options": true, "invalid": "That isn't one of the choices.",
"retries": 2, "timeout_s": 7, "fallback": "vm"}
key must be a single keypad key: 0–9,
* or #. Words are not accepted — a caller has a keypad, not a
keyboard. Up to 12 options, each with a label the caller can hear.
With show_options (default true) the platform appends "For sales, press
one." for each option, with the digit spoken as a word. Set it false to write the whole
prompt yourself.
A wrong key or silence re-prompts up to retries times (0–5), then takes
fallback — or says goodbye and hangs up if there is none. Always set a
fallback: it is also where the call goes on a number that cannot hear
keypresses at all.
ask
Collect several digits — an account number, a ZIP, a date.
{"type": "ask", "text": "Enter your account number, then press pound.",
"save_as": "account_no", "digits": 10, "finish_on_hash": true,
"timeout_s": 12, "retries": 2, "next": "lookup", "fallback": "vm"}
Saves the digits under save_as for later steps. Digits only — there is no speech
recognition.
confirm
A yes/no question with a fixed shape: 1 is yes, 2 is no.
{"type": "confirm", "text": "Is this about an existing order?",
"yes_label": "yes", "no_label": "no", "yes": "orders", "no": "general",
"retries": 2, "fallback": "vm"}
ring_group
Try a team until somebody answers. The platform dials one member at a time and moves on when a
member does not pick up; strategy: "all" rings everyone at once where the number
can do it.
{"type": "ring_group",
"numbers": [{"to": "+15551230001", "label": "Ann"}, {"to": "+15551230002", "label": "Raj"}],
"strategy": "sequence", "connect": "bridge", "timeout_s": 20,
"announce": "One moment please.", "whisper": "Call from {{caller}}.",
"on_fail": "vm", "next": "bye"}
Up to 10 numbers. whisper is played to whoever answers, before the caller is
joined. on_fail is taken once every member has been tried.
directory
Dial by extension.
{"type": "directory", "text": "Enter the three digit extension.",
"ext_digits": 3,
"extensions": [{"digits": "101", "label": "Sales", "to": "+15551230001"},
{"digits": "102", "label": "Support", "next": "support_menu"}],
"connect": "bridge", "connecting": "One moment please.",
"retries": 2, "fallback": "menu", "on_fail": "vm"}
Each entry either rings a number (to) or jumps to a step (next). Every
extension must be exactly ext_digits long. Up to 60 entries.
hold
Reassure, wait, repeat — for use between ring attempts.
{"type": "hold", "text": "Thanks for waiting, we are still trying to reach someone.",
"rounds": 2, "every_s": 20, "next": "vm"}
holiday
{"type": "holiday", "dates": ["12-25", "01-01", "2026-11-26"],
"next": "closed", "else": "open"}
12-25 repeats every year; 2026-11-26 is one-off. Leave
dates empty to use the flow's own holidays list, so one list can serve
every holiday check in the flow.
tag
Label the call for reporting. Never spoken; it comes back on the call object and in
call.completed.
{"type": "tag", "tags": "sales, after-hours", "next": "ring"}
goto_flow
Hand the call to another flow on the same number — the way to share a voicemail or a menu between flows instead of copying it.
{"type": "goto_flow", "flow": "vf_…"}
The call keeps its id and its recording announcement is not replayed. Up to 3 hand-offs per call, so flows cannot ring round in a circle.
forward · bridge
{"type": "forward", "to": "+15551234567", "timeout_s": 30,
"announce": "One moment please.", "on_fail": "vm", "next": "bye"}
forward hands the call over; bridge joins caller and callee and may
carry a whisper line played to the person answering. to must be a
US/Canada number (premium and Caribbean ranges are refused) and may be a placeholder such as
{{agent_number}}. on_fail catches nobody answering — and also a
number that cannot transfer at all.
voicemail · record
{"type": "voicemail", "text": "Leave a message after the tone.",
"max_s": 120, "beep": true, "transcribe": false, "next": "bye"}
{"type": "record", "action": "start", "next": "menu"} // or "stop"
max_s is 5–600. Neither can run before the announcement has played — that is an
engine invariant, so there is no ordering you can write that defeats it.
hours
{"type": "hours", "days": [1,2,3,4,5], "from": "09:00", "to": "17:00",
"tz": "America/New_York", "next": "open", "else": "closed"}
Days are ISO (1 = Monday … 7 = Sunday); [] means every day. A window that wraps
midnight belongs to the day it starts on. Omit tz to use the flow's.
branch · set
{"type": "branch", "rules": [{"var": "digits", "op": "equals", "value": "1", "next": "a"}],
"else": "b"}
{"type": "set", "vars": [{"name": "queue", "value": "sales"}], "next": "x"}
Operators: equals, not_equals, contains,
starts_with, one_of, greater, less,
is_empty, not_empty. Comparison is case-insensitive;
one_of takes a comma-separated list.
webhook
Call your own API mid-call — look up an account, pick an agent. Same fields as a flow API step. Your JSON reply may steer the call:
{"say": "Your balance is twelve dollars.", "vars": {"tier": "gold"},
"goto": "vip", "hangup": false}
Keep it fast: the caller hears silence while it runs. The timeout is 8 seconds, then
on_error is taken.
sms · notify
{"type": "sms", "to": "caller", "text": "Here's the link we mentioned: …", "next": "bye"}
{"type": "notify", "to": "+15551112222", "text": "Missed call from {{caller}}.", "next": "bye"}
to: "caller" texts whoever is on the call. These go out through the ordinary send
path, so they are billed, limited and logged like any other message. Up to 5 per call.
pause · hangup · end
{"type": "pause", "seconds": 2, "next": "x"}
{"type": "hangup", "text": "Thanks, goodbye."}
end is a synonym of hangup.
Values & placeholders
Any text field takes {{name}} placeholders. Built in:
{{caller}} (704) 555-0123 {{caller_e164}} +17045550123
{{number}} the number they called {{number_e164}} +19802904746
{{digits}} the last keys pressed {{flow}} the flow's name
{{date}} Oct 25, 2026 {{time}} 9:14 AM
{{call_id}} vc_…
Plus anything you saved with ask, set or a webhook, with dots into
JSON results: {{api.customer.name}}. An unknown name renders as empty — it is
never left visible as {{…}}, because the caller would hear it read aloud.
Remember these are spoken. {{caller}} reads out
as digits; a long API string will be read in full.
Worked example
Business hours → forward; outside them → voicemail and a text to the caller.
curl -X POST https://sms.bodek.us/api/v1/calls/flows \
-H "Authorization: Bearer $BODEK_KEY" -H "Content-Type: application/json" -d '{
"number_id": 8,
"name": "Main line",
"announce": "This call is recorded for quality and training.",
"record_mode": "steps",
"retain_days": 30,
"tz": "America/New_York",
"definition": {
"start": "hours",
"steps": {
"hours": {"type": "hours", "days": [1,2,3,4,5], "from": "09:00", "to": "17:00",
"next": "greet", "else": "closed"},
"greet": {"type": "menu", "text": "Thanks for calling.",
"options": [{"key": "1", "label": "sales", "next": "sales"},
{"key": "2", "label": "to leave a message", "next": "vm"}],
"retries": 2, "fallback": "vm"},
"sales": {"type": "forward", "to": "+17045550123",
"announce": "Connecting you now.", "on_fail": "vm"},
"closed": {"type": "say", "text": "We are closed. Our hours are nine to five, Monday to Friday.",
"next": "vm"},
"vm": {"type": "voicemail", "text": "Please leave a message after the tone.",
"max_s": 120, "next": "txt"},
"txt": {"type": "sms", "to": "caller",
"text": "Thanks for calling - we got your message and will call you back.",
"next": "bye"},
"bye": {"type": "hangup", "text": "Thanks, goodbye."}
}
}
}'
The reply carries the flow plus errors, warnings,
needs and unsupported. Create it without "active": true
first, read unsupported, then activate:
POST /v1/calls/flows/vf_…/activate
Activation is refused with 409 flow_invalid while the definition has errors, and
the response lists them per step so a build script can fix and retry.
Calls & recordings
GET /v1/calls/voice?status=done&limit=20
{"id": "vc_…", "caller": "+17045550123", "hidden": false,
"flow_id": "vf_…", "driver": "phone", "status": "done", "outcome": "completed",
"step": null, "steps": 7, "prompts": 4, "last_digits": "2",
"recording": "stopped", "forwarded_to": null,
"consent": {"announced": true,
"announcement": "This call is recorded for quality and training.",
"announced_at": "2026-10-25T14:02:11+00:00"},
"duration_s": 48, "started_at": "…", "answered_at": "…", "ended_at": "…"}
Filters: number_id, flow_id, status,
caller, limit, before_id. Statuses are
ringing, answered, active, transferring,
bridged, done, failed, abandoned
(abandoned means the phone stopped reporting mid-call and the platform closed it).
GET /v1/calls/voice/{id} adds the step-by-step log and the call's
recordings. The log is the ground truth for what the caller actually heard,
including any unsupported entry where the number fell short of the flow.
Download audio with GET /v1/calls/recordings/{id}; the response carries
X-Bodek-Announcement with the exact words that call was given. Add
?meta=1 for the metadata instead. After retain_days the audio is
purged and the download answers 410 gone while the metadata remains.
Call webhooks
Subscribe on SMS events → Webhooks, or to the whole family with
call.*. See SMS Webhooks for signing and retries.
| Event | When |
|---|---|
call.received | a call reached your number, before it is answered (answering says whether a flow took it) |
call.answered | answered and a flow started |
call.consent | the announcement was played — carries the exact words and the time |
call.input | the caller pressed a key |
call.forwarded | forwarded or bridged, with to and mode |
call.recorded | a recording is ready, with its download url and purge_after |
call.completed | the flow finished and the call ended |
call.failed | the flow could not run or ended in an error |
call.missed | an inbound call was not answered |
call.unsupported | the flow needed something this number cannot do — carries the primitive |
voice_flow.updated | a call flow was created, changed, activated, paused or deleted |
Opt-out keywords are a texting idea and do not apply to calls; the opt-out policy is unchanged by anything here.
Limits
| Call flows per number | 20 |
| Steps per flow | 100 |
| Steps without caller input | 40 (loop guard) |
| Spoken prompts per call | 30 |
| Characters per prompt | 1000 |
| Menu options | 12 |
| Texts per call | 5 |
| Call length | 1 hour |
| Recording length | 600 s per step, 20 MB per upload |
| Caller list | 500 entries |
| Flow changes | 60 per minute per account |
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_number | number_id missing on create |
| 400 | invalid_flow | a field was rejected; message says which |
| 400 | bad_request | malformed body |
| 403 | insufficient_scope | the key lacks voice:read / voice:write |
| 403 | number_not_allowed | the key is bound to a different number |
| 404 | not_found | no such flow, call or recording on this account |
| 409 | flow_invalid | cannot activate: the response's error.errors lists what to fix |
| 410 | gone | the audio was purged; the metadata remains |
| 429 | rate_limited | too many changes; see Retry-After |
A definition error on create or save is not a failed request: the flow is
stored as an inactive draft and errors tells you exactly what to fix, so a build
script can PATCH and try again.