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.

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.

PrimitiveNeeded byIf the number cannot do it
playevery step that speaks the call is answered in silence — check this first
gathermenu, ask the prompt is read out, then the step's fallback is taken
dial_transferforward on_fail is taken (usually voicemail)
dial_bridgebridgeas above
recordvoicemail, record a short apology is spoken and the flow continues
smssms, 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

MethodPathWhat it does
GET/v1/calls/flowsyour call flows (?expand=definition for the steps)
POST/v1/calls/flowscreate one (optionally active, with a full definition)
GET/v1/calls/flows/templatesstarter definitions to build from
GET/v1/calls/flows/schemaevery step type and its fields, for building your own editor
POST/v1/calls/flows/validatecheck 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}/activateswitch it on (refused while it has errors)
POST/v1/calls/flows/{id}/pauseswitch it off
POST/v1/calls/flows/{id}/rotate_secretnew signing secret for its API steps
GET/v1/calls/voiceanswered calls that ran a flow
GET/v1/calls/voice/{id}one call, with its log and recordings
GET/v1/calls/voice/{id}/logits step-by-step history
GET/v1/calls/recordingsrecordings 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_idrequired on create — which of your numbers answers
nameup to 120 characters
activeswitched on. A flow with definition errors is forced inactive
callersany · hidden · list · not_list · members · not_members
caller_listE.164 numbers, or prefixes ending in * (e.g. +1800*), up to 500
priority−100…100, highest wins when several flows match a call
tzIANA zone for hours steps and {{time}}
announcethe announcement wording. Empty restores the default — it cannot be switched off
record_modesteps · all · off
retain_days1–3650, default 90
voice_namepreferred speaking voice (a hint — the number picks the closest it has)
voice_ratespeaking speed, 50–200 (percent)
max_call_slongest a call may run, 30–3600 (default 1800)
holidaysdates 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.

EventWhen
call.receiveda call reached your number, before it is answered (answering says whether a flow took it)
call.answeredanswered and a flow started
call.consentthe announcement was played — carries the exact words and the time
call.inputthe caller pressed a key
call.forwardedforwarded or bridged, with to and mode
call.recordeda recording is ready, with its download url and purge_after
call.completedthe flow finished and the call ended
call.failedthe flow could not run or ended in an error
call.missedan inbound call was not answered
call.unsupportedthe flow needed something this number cannot do — carries the primitive
voice_flow.updateda 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 number20
Steps per flow100
Steps without caller input40 (loop guard)
Spoken prompts per call30
Characters per prompt1000
Menu options12
Texts per call5
Call length1 hour
Recording length600 s per step, 20 MB per upload
Caller list500 entries
Flow changes60 per minute per account

Errors

StatusCodeMeaning
400invalid_numbernumber_id missing on create
400invalid_flowa field was rejected; message says which
400bad_requestmalformed body
403insufficient_scopethe key lacks voice:read / voice:write
403number_not_allowedthe key is bound to a different number
404not_foundno such flow, call or recording on this account
409flow_invalidcannot activate: the response's error.errors lists what to fix
410gonethe audio was purged; the metadata remains
429rate_limitedtoo 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.