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

  1. A trigger fires: a missed call, a keyword, any text, or POST /v1/flows/{id}/start.
  2. A run (one conversation with one person) opens and the engine executes steps from start onward.
  3. It runs until it reaches a step that waits for a reply (menu, ask) or one that ends the conversation (end, or a step whose next is empty).
  4. 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.
  5. No reply within the flow's timeout_min and the run expireds.

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

EndpointScopePurpose
GET /v1/flows
flows:readYour flows. ?expand=definition includes the steps.
POST /v1/flows
flows:writeCreate one, optionally complete and active in a single call.
GET /v1/flows/templates
flows:readStarter definitions to build from.
POST /v1/flows/validate
flows:writeCheck a definition without storing it.
GET /v1/flows/{id}
flows:readOne flow with its definition and its API-step secret.
PATCH /v1/flows/{id}
flows:writeChange any subset of fields.
PUT /v1/flows/{id}
flows:writeReplace it — anything you leave out goes back to its default.
DELETE /v1/flows/{id}
flows:writeDelete it and stop its open runs.
POST /v1/flows/{id}/activate
flows:writeSwitch it on (refused while it has errors or a trigger clash).
POST /v1/flows/{id}/pause
flows:writeSwitch it off and stop its open runs.
POST /v1/flows/{id}/rotate_secret
flows:writeNew signing secret for its API steps.
POST /v1/flows/{id}/start
flows:runText the flow to someone now.
GET /v1/flows/{id}/runs
flows:readThat flow's conversations.
GET /v1/flows/runs
flows:readConversations across all your flows.
GET /v1/flows/runs/{id}
flows:readOne conversation: status and saved values.
GET /v1/flows/runs/{id}/log
flows:readIts step-by-step history.
POST /v1/flows/runs/{id}/stop
flows:writeEnd 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:

POST /v1/flows/validate
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

POST /v1/flows/{id}/start
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

GET /v1/flows/runs/{id}
{ "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": "…"
} }
GET /v1/flows/runs

Query: flow_id, number_id, phone, status, before_id, limit (max 200). Page with next_before_id.

GET /v1/flows/runs/{id}/log
{ "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.

POST /v1/flows/runs/{id}/stop

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 number25
Steps per flow100
Steps executed without waiting for a reply40 (loop guard)
Messages per conversation40
Flow texts to one person per number per day60
New conversations one person can start per number10 per hour
API-step calls per run5, 20 s of HTTP in total
Staff alerts / rings per run10 / 3 (300 / 40 per number per day)
/start calls60 per minute per flow
Flow writes60 per minute per account
Message text1,600 characters
Run timeout / restart cooldowntimeout_min 5–10080, cooldown_min 0–10080
DestinationsUS 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

StatusCodeMeaning
400invalid_flowNo usable name, or the number isn't one of yours.
400invalid_numbernumber_id / to missing or not a valid number.
400invalid_varsvars must be an object of names to values (max 8 KB).
403insufficient_scopeThe key lacks flows:read / flows:write / flows:run.
403number_not_allowedThe key is bound to a different number.
404not_foundNo such flow or run on this account.
409flow_not_activatableErrors in the definition, no trigger, or a trigger clash. See errors.
409flow_inactive/start on a flow that is switched off.
409group_memberThat number belongs to a group on this number, so their texts go to the group.
409run_not_activeThe run had already finished.
429rate_limitedFlow 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.