SMS Flows API
A flow is a text conversation on one of your numbers: menus and submenus, questions whose answers you keep, calls out to your own API mid-conversation, if/otherwise branches, staff alerts. It can start when someone misses a call to the number, texts a keyword, texts anything at all, or when you start it from your server.
Everything the editor on sms.bodek.us can do, this API can do. It is the same definition format
and the same validator, so a flow your platform builds opens, reads and edits normally in the
browser, and a flow built in the browser round-trips through GET →
PATCH without losing anything.
Base https://sms.bodek.us/api/v1
Auth Authorization: Bearer bs_live_…
Scopes flows:read list flows, read definitions and runs
flows:write create, change, activate, pause, delete, stop runs
flows:run start a flow for a number
Flows need a number dedicated to your account — the shared sending pool can't host one. Request a dedicated number on sms.bodek.us → Numbers.
How a flow works
- A trigger fires: a missed call, a keyword, any text, or
POST /v1/flows/{id}/start. - A run (one conversation with one person) opens and the engine executes
steps from
startonward. - It runs until it reaches a step that waits for a reply (
menu,ask) or one that ends the conversation (end, or a step whosenextis empty). - Their reply resumes the run from where it waited. Answers are saved as named values you can use later in the conversation or read off the run afterwards.
- No reply within the flow's
timeout_minand the runexpireds.
Runs happen out of band, on a worker — normally within a second of the text arriving. Nothing in a flow ever blocks a message send.
One person has at most one open run per number: a new trigger replaces the one before it. Group members on a number are never routed into a flow — their texts always go to their group.
Endpoints
| Endpoint | Scope | Purpose |
|---|---|---|
GET /v1/flows | flows:read | Your flows. ?expand=definition includes the steps. |
POST /v1/flows | flows:write | Create one, optionally complete and active in a single call. |
GET /v1/flows/templates | flows:read | Starter definitions to build from. |
POST /v1/flows/validate | flows:write | Check a definition without storing it. |
GET /v1/flows/{id} | flows:read | One flow with its definition and its API-step secret. |
PATCH /v1/flows/{id} | flows:write | Change any subset of fields. |
PUT /v1/flows/{id} | flows:write | Replace it — anything you leave out goes back to its default. |
DELETE /v1/flows/{id} | flows:write | Delete it and stop its open runs. |
POST /v1/flows/{id}/activate | flows:write | Switch it on (refused while it has errors or a trigger clash). |
POST /v1/flows/{id}/pause | flows:write | Switch it off and stop its open runs. |
POST /v1/flows/{id}/rotate_secret | flows:write | New signing secret for its API steps. |
POST /v1/flows/{id}/start | flows:run | Text the flow to someone now. |
GET /v1/flows/{id}/runs | flows:read | That flow's conversations. |
GET /v1/flows/runs | flows:read | Conversations across all your flows. |
GET /v1/flows/runs/{id} | flows:read | One conversation: status and saved values. |
GET /v1/flows/runs/{id}/log | flows:read | Its step-by-step history. |
POST /v1/flows/runs/{id}/stop | flows:write | End a conversation now. |
A flow object
{
"id": 5,
"name": "Front desk",
"number_id": 12,
"number": "+15551230000",
"active": true,
"triggers": { "missed_call": true, "any_text": false, "keywords": ["MENU", "INFO"] },
"cooldown_min": 10, // don't restart for the same person within this many minutes
"timeout_min": 60, // a run with no reply expires after this
"runs": 418, // lifetime count
"active_runs": 3,
"last_run_at": "2026-10-25T14:03:11+00:00",
"step_secret": "a1b2c3…", // signs this flow's API-step requests
"definition": { "start": "main", "steps": { … } },
"created_at": "…", "updated_at": "…"
}
The definition format
A definition is a start step id and a map of steps keyed by id. Steps are linked by id, so a flow is a graph, not a list — order in the object means nothing.
{
"start": "main",
"steps": {
"main": { "type": "menu", … },
"hours": { "type": "say", … },
"bye": { "type": "end", … }
}
}
Step ids: [A-Za-z0-9][A-Za-z0-9_]{0,39} — your own names, stable across edits, and
what goto in an API step reply and
waiting_on_step on a run refer to. Pick meaningful ones.
Every save is normalised: unknown fields are dropped, text is trimmed and
capped, links to steps that don't exist are cleared (with an error telling you which), and
numbers are clamped to their range. What you read back from GET is exactly what
the engine will run — never your input echoed.
An empty next (or an end step) finishes the conversation.
Step reference
Every step takes an optional label (≤ 60 chars, shown in the editor and the run
log). Message text is up to 1,600 characters and may contain
placeholders.
say — send a message and carry on
{ "type": "say", "label": "Hours", "text": "We're open Mon–Fri 9–5.", "next": "bye" }
menu — offer numbered choices and wait
{ "type": "menu", "label": "Main menu",
"text": "Sorry we missed your call! Reply with a number:",
"show_options": true, // append "1) Hours 2) Location …" automatically
"options": [
{ "key": "1", "label": "Hours", "also": "hours, open", "next": "hours" },
{ "key": "2", "label": "Location", "also": "address, where", "next": "where" },
{ "key": "3", "label": "Call me", "also": "callback, call me", "next": "ask_name" }
],
"invalid": "Sorry, that's not an option.",
"retries": 2, // 0–5 wrong replies before giving up
"fallback": "bye" // where to go then (empty = end the conversation)
}
A reply matches an option's key, its label, any word in
also, or a leading token that equals a key (so "1.",
"#1" and "1 please" all pick option 1). Up to 20 options; two options
may not resolve to the same word.
ask — ask a question and save the answer
{ "type": "ask", "label": "Order number", "text": "What's your order number?",
"save_as": "order", // the value name — letters, digits, _
"expect": "digits", // any | number | digits | email | yes_no | phone
"invalid": "Please reply with digits only.",
"retries": 2, "next": "lookup", "fallback": "bye" }
expect both validates and normalises: yes_no saves
"yes"/"no" from any of the usual words, phone saves
E.164, email saves it lower-cased, number strips
$ and ,. A reply that doesn't validate sends
invalid and asks again.
branch — take a different path
{ "type": "branch", "label": "Shipped?",
"rules": [
{ "var": "api.status", "op": "equals", "value": "shipped", "next": "shipped" },
{ "var": "total", "op": "greater", "value": "100", "next": "vip" },
{ "var": "plan", "op": "one_of", "value": "gold, silver", "next": "priority" },
{ "var": "note", "op": "not_empty", "value": "", "next": "review" }
],
"else": "not_yet" }
Rules are tried in order; the first match wins. var may be a dotted path into a
saved object (api.status, api.order.state). Up to 20 rules.
Operators: equals, not_equals, contains,
starts_with, one_of (comma-separated value),
greater, less, is_empty, not_empty.
set — save values without asking
{ "type": "set", "label": "Tag it",
"vars": [ { "name": "source", "value": "missed_call" },
{ "name": "greeting", "value": "Hi {{name}}" } ],
"next": "main" }
webhook — call your API mid-conversation
{ "type": "webhook", "label": "Look up order",
"method": "GET", // GET or POST
"url": "https://your.app/api/orders/{{order}}",
"headers": [ { "name": "Authorization", "value": "Bearer …" } ],
"body_type": "default", // default | json | form
"body": "",
"save_as": "api", // the reply lands here: {{api.status}}
"next": "check", "on_error": "oops" }
See API steps for the request we send, what your reply can do, and how to verify its signature.
notify — text your staff
{ "type": "notify", "label": "Tell the front desk",
"to": "+15551230001, +15551230002", // up to 5 US/Canada numbers
"text": "Call back {{name}} at {{caller}}: {{reason}}", "next": "bye" }
ring — make the number ring a phone
{ "type": "ring", "label": "Ring the manager",
"to": "+15551230001", "seconds": 20, "next": "bye" }
join_group — add them to a group on this number
{ "type": "join_group", "label": "Join the team list",
"group_id": 7, "name": "{{first_name}}", "next": "welcome", "on_error": "full" }
The group must be on this flow's number and owned by the same account.
end — last message, then stop
{ "type": "end", "label": "Goodbye", "text": "Got it, {{name}}. We'll call you back soon." }
Values & placeholders
Any text in a step may contain {{name}}, filled from the run's values. Missing
names render empty. These are always available:
{{caller}} | The person's number, formatted — (555) 765-4321. |
{{caller_e164}} | The same number as +15557654321. |
{{number}} / {{number_e164}} | Your number, formatted / E.164. |
{{date}} / {{time}} | Oct 25, 2026 / 2:03 PM, in the number's timezone. |
{{flow}} / {{trigger}} | The flow's name / what started this run. |
{{input}} | What they texted to start a keyword or any-text run. |
Those names are reserved — an ask or set cannot overwrite them. Your
own names are [A-Za-z_][A-Za-z0-9_]{0,31}. Values you pass to
/start are available from the first step, which is how you personalise an outbound
flow. Read everything a run collected from
GET /v1/flows/runs/{id} or from the
flow webhooks.
Validating & activating
Check a definition before you store it:
curl -X POST https://sms.bodek.us/api/v1/flows/validate \
-H "Authorization: Bearer bs_live_…" -H "Content-Type: application/json" \
-d '{ "definition": { "start": "main", "steps": { … } } }'
{
"ok": true,
"valid": false,
"errors": [ { "step": "main", "message": "Choice \"2\" points to a step that no longer exists." } ],
"warnings": [ { "step": "orphan", "message": "Not reachable from the first step." } ],
"definition": { … the normalised form we would store … }
}
A flow with errors is never lost. POST /v1/flows and
PATCH /v1/flows/{id} store it as an inactive draft and return the errors
alongside the flow, so a build script can fix and re-send. The call succeeds —
check errors, not the HTTP status.
Switching a flow on requires: no errors, at least one trigger, and no clash with another
active flow on the same number (two flows can't both answer missed calls, both answer
any text, or share a keyword). Set "active": true on a write, or call
/activate; if it can't be switched on you get
409 flow_not_activatable with the
reasons in errors.
Worked example — build and launch in one call
curl -X POST https://sms.bodek.us/api/v1/flows \
-H "Authorization: Bearer bs_live_…" -H "Content-Type: application/json" \
-d '{
"name": "Order status",
"number_id": 12,
"active": true,
"keywords": ["STATUS", "ORDER"],
"on_missed_call": false,
"timeout_min": 30,
"cooldown_min": 5,
"definition": {
"start": "ask_order",
"steps": {
"ask_order": { "type": "ask", "label": "Order number",
"text": "Hi! What is your order number?",
"save_as": "order", "expect": "digits",
"invalid": "Digits only, please.", "retries": 2,
"next": "lookup", "fallback": "handoff" },
"lookup": { "type": "webhook", "label": "Look it up", "method": "GET",
"url": "https://your.app/api/orders/{{order}}",
"save_as": "api", "next": "check", "on_error": "handoff" },
"check": { "type": "branch", "label": "Shipped?",
"rules": [ { "var": "api.status", "op": "equals", "value": "shipped", "next": "shipped" } ],
"else": "pending" },
"shipped": { "type": "end", "label": "Shipped",
"text": "Order {{order}} shipped! Tracking: {{api.tracking}}" },
"pending": { "type": "end", "label": "Pending",
"text": "Order {{order}} is {{api.status}}. We will text you when it ships." },
"handoff": { "type": "notify", "label": "Tell the team",
"to": "+15551230001",
"text": "Could not help {{caller}} with order {{order}}.", "next": "sorry" },
"sorry": { "type": "end", "text": "Sorry — someone will get back to you shortly." }
}
}
}'
→ 201 { "ok": true, "flow": { "id": 9, "active": true, … }, "errors": [], "warnings": [] }
Then change one thing without resending the rest:
curl -X PATCH https://sms.bodek.us/api/v1/flows/9 \
-H "Authorization: Bearer bs_live_…" -H "Content-Type: application/json" \
-d '{ "keywords": ["STATUS", "ORDER", "TRACK"] }'
Runs (conversations)
Start one for someone
curl -X POST https://sms.bodek.us/api/v1/flows/5/start \
-H "Authorization: Bearer bs_live_…" -H "Content-Type: application/json" \
-d '{ "to": "+15557654321", "vars": { "name": "Ann", "appt": "Tue 3pm" } }'
→ 202 { "ok": true, "run": { "id": 431, "flow_id": 5, "to": "+15557654321", "status": "active" } }
Needs flows:run. vars are available as {{name}} from the
first step. 60 starts per minute per flow. Flow texts count toward your daily message allowance
like any other send.
Follow one
{ "ok": true, "run": {
"id": 431, "flow_id": 5, "number_id": 12, "to": "+15557654321",
"trigger": "api", // api | keyword | text | missed_call
"status": "active", // active | done | expired | stopped | error
"waiting_on_step": "confirm", // null when it isn't waiting
"messages_sent": 2, "steps": 4,
"vars": { "name": "Ann", "appt": "Tue 3pm", "confirm": "yes" },
"started_at": "…", "updated_at": "…", "expires_at": "…"
} }
Query: flow_id, number_id, phone, status,
before_id, limit (max 200). Page with
next_before_id.
{ "ok": true, "run_id": 431, "log": [
{ "step": null, "kind": "start", "detail": "Started by api", "at": "…" },
{ "step": "ask_order", "kind": "reply", "detail": "Hi! What is your order number?", "at": "…" },
{ "step": "ask_order", "kind": "answer", "detail": "order = 10442", "at": "…" },
{ "step": "lookup", "kind": "webhook", "detail": "GET https://your.app/… → HTTP 200 (84 ms)", "at": "…" },
{ "step": null, "kind": "end", "detail": "Done", "at": "…" }
] }
Kept 30 days. For live updates subscribe to the flow webhooks instead of polling.
Ends an active run at once. 409
run_not_active if it had already finished.
API steps
A webhook step calls your server in the middle of a conversation and can let your
reply steer it. The default body:
POST https://your.app/sms-hook
Content-Type: application/json
X-Bodek-Flow-Id: 5
X-Bodek-Session-Id: 431
X-Bodek-Signature: t=1792000000,v1=5f0c… // HMAC-SHA256(step_secret, "<t>.<raw body>")
{"event": "flow.step", "flow_id": 5, "flow": "Front desk", "session_id": 431, "step": "lookup",
"trigger": "missed_call", "caller": "+15557654321", "number": "+15551230000",
"input": "2", "vars": {"name": "Ann", "order": "10442"}, "timestamp": "2026-10-25T14:03:40+00:00"}
Or send your own JSON / form body, or a GET with {{values}} in the
URL. Reply within 8 seconds with any 2xx. A JSON reply is saved under the step's
save_as (so {{api.status}} works) and these keys act on the
conversation:
{ "reply": "Your order shipped today.", // texted to the person
"vars": { "tracking": "1Z999" }, // saved for later steps
"goto": "step_id", // jump to a step
"end": true } // or finish the conversation
Anything else — a timeout, a non-2xx, a redirect — takes the step's on_error path.
Verify the signature exactly as for a
platform webhook, using the flow's
step_secret (from GET /v1/flows/{id}, rotatable with
/rotate_secret).
Limits per run: 5 API calls, 20 seconds of HTTP in total, 120 calls per minute per flow. The same network rules as every outbound request we make: public addresses only, no redirects followed, responses capped at 64 KB.
Don't confuse the two. An API step is a request your flow makes, mid-conversation, whose reply changes the conversation. A platform webhook is a notification we push to you about something that happened. They have separate secrets.
Flow webhooks
Subscribe an endpoint to flow.* and you get flow.run.started,
flow.run.step, flow.run.input, flow.run.completed,
flow.run.expired, flow.run.stopped, flow.run.error and
flow.updated — enough to mirror a conversation in your own system as it happens,
and to notice when someone edits a flow in the browser that your platform manages. Payloads and
the signature scheme are in SMS Webhooks → Flow events.
Opt-outs in flows
No keyword is reserved, and a flow never stops on its own. If
someone texts STOP to a number running a flow, Bodek SMS records it and raises
message.opt_out — and then treats the text like any other reply. A keyword flow
may trigger on it, an open conversation continues, and /start still works for
that number.
Bodek SMS stops delivery only when Bodek administration stops it. Receiving the webhook and stopping delivery is your responsibility, and failing to do so can result in suspension of your Bodek SMS service. See the full opt-out policy.
If you want a flow to acknowledge an opt-out, build it: give the flow a keyword like
STOP, or add a branch on {{input}}, and have it
say whatever your compliance process requires. Then suppress the recipient in your
own system — a flow step cannot do that for you.
// Example: a flow that confirms an opt-out and alerts your team.
{ "start": "confirm", "steps": {
"confirm": { "type": "say", "text": "You're unsubscribed. Reply START to resume.", "next": "tell_us" },
"tell_us": { "type": "webhook", "method": "POST", "url": "https://your.app/api/suppress",
"body_type": "json", "body": "{\"phone\":\"{{caller_e164}}\"}",
"save_as": "api", "next": "", "on_error": "" }
} }
// …with "keywords": ["STOP","UNSUBSCRIBE","CANCEL"] on the flow.
Treat that as a courtesy to the recipient, not as compliance. The authoritative signal is the
message.opt_out webhook and
GET /v1/opt-outs.
Limits
| Flows per number | 25 |
| Steps per flow | 100 |
| Steps executed without waiting for a reply | 40 (loop guard) |
| Messages per conversation | 40 |
| Flow texts to one person per number per day | 60 |
| New conversations one person can start per number | 10 per hour |
| API-step calls per run | 5, 20 s of HTTP in total |
| Staff alerts / rings per run | 10 / 3 (300 / 40 per number per day) |
/start calls | 60 per minute per flow |
| Flow writes | 60 per minute per account |
| Message text | 1,600 characters |
| Run timeout / restart cooldown | timeout_min 5–10080, cooldown_min 0–10080 |
| Destinations | US and Canada only (premium-rate and Caribbean area codes excluded) |
Flow messages are billed exactly like any other send and count toward the account's daily allowance; past it they're rejected unless pay-as-you-go is on. A flow is switched off automatically if its number is reassigned or released, and a run stops if the owner's SMS plan lapses.
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_flow | No usable name, or the number isn't one of yours. |
| 400 | invalid_number | number_id / to missing or not a valid number. |
| 400 | invalid_vars | vars must be an object of names to values (max 8 KB). |
| 403 | insufficient_scope | The key lacks flows:read / flows:write / flows:run. |
| 403 | number_not_allowed | The key is bound to a different number. |
| 404 | not_found | No such flow or run on this account. |
| 409 | flow_not_activatable | Errors in the definition, no trigger, or a trigger clash. See errors. |
| 409 | flow_inactive | /start on a flow that is switched off. |
| 409 | group_member | That number belongs to a group on this number, so their texts go to the group. |
| 409 | run_not_active | The run had already finished. |
| 429 | rate_limited | Flow writes or /start over the limit; see Retry-After. |
Errors inside a definition are not HTTP errors: the write succeeds, the flow is kept as
a draft, and the problems come back in errors / warnings with the step
id each one belongs to.