SMS API
Send and receive text messages, list your numbers, and manage group texting from your server. Unlike the other APIs, the SMS API is served by sms.bodek.us directly — not the dev gateway. You create and manage keys here on SMS API keys.
Base https://sms.bodek.us/api/v1
Auth Authorization: Bearer bs_live_…
| Endpoint | Scope | Purpose |
|---|---|---|
GET /v1/health | — | Service check |
GET /v1/numbers | numbers:read | Your usable numbers |
GET /v1/numbers/{id} | numbers:read | Is one number live? |
POST /v1/numbers/status | numbers:read | Check several at once |
POST /v1/messages | messages:send | Send to one or more numbers |
GET /v1/messages | messages:read | List messages |
GET /v1/messages/{id} | messages:read | One message |
DELETE /v1/messages/{id} | messages:send | Cancel a queued message |
GET /v1/media/{token} | messages:read | Download an attachment |
GET /v1/groups | groups:read | List groups |
POST /v1/groups/{id}/messages | messages:send | Broadcast to a group |
GET /v1/webhooks | webhooks:read | Webhook endpoints |
GET /v1/opt-outs | optouts:read | Who asked you to stop |
GET /v1/flows | flows:read | Flows (full CRUD) |
GET /v1/calls/flows | voice:read | Call flows — what a caller hears |
Three companion references cover the parts that are big enough to need their own page: SMS Webhooks (inbound events, opt-outs, every delivery status, signature verification), SMS Flows API (build and manage text conversations entirely over the API) and SMS Call Flows (what a caller hears: spoken menus, forwarding, voicemail and recordings).
Authentication
Send your key as a bearer token. Keys are server-side credentials — never ship one in a
browser or mobile app. A revoked key, or an account whose plan no longer includes SMS, stops
working immediately (401 invalid_key / 402 subscription_inactive).
Authorization: Bearer bs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
A key can be bound to one number. A bound key can only send from — and only sees messages on — that number.
Revoking and deleting a key
Keys go in two stages on SMS API keys. Revoke stops a
key working immediately — the next request gets
401 invalid_key — and keeps it
listed so you can see what used to exist while you fix whatever was using it.
Delete is then offered on a revoked key and erases it for good: the secret,
the name, the permissions and the number binding, along with its idempotency records.
Deleting a key does not delete the messages it sent. Delivery history, the opt-out record and your billing records are the account's, not the key's, so they stay intact and the key's id stays resolvable if support ever has to trace old traffic. There is no API route for either action — a leaked key cannot revoke or delete itself, or erase its own trail.
Requests & responses
- All requests and responses are JSON.
- Every response is an envelope:
{"ok": true, …}on success or{"ok": false, "error": {"code": "…", "message": "…"}}on failure. - Each response carries an
X-Request-Idheader — quote it in support requests. - Phone numbers are E.164 (
+15551234567); US 10-digit input is accepted and normalised. A message body is up to 1,600 characters (~10 segments). - A send returns 202 with the queued messages. Get delivery status by webhook (recommended) or by polling GET /v1/messages/{id}.
Message ids
Every message has an opaque, unguessable id — msg_ plus 32 hex characters from a
CSPRNG:
"id": "msg_af6d1cbbb042d08e5ddeef055306fd5a" // the secure id — use this everywhere
"seq": 48125 // the row number, for since_id / before_id paging
That id is what every response and every webhook payload carries, and what
/v1/messages/{id} takes. It can be logged, passed between systems or quoted in a
support ticket without revealing how much traffic anyone sends, and nobody can walk your
history by counting. Paging cursors still use seq, because they need an ordered
value. /v1/messages/{id} accepts either form, so code written against the old
numeric ids keeps working.
Other ids follow the same pattern: webhook endpoints are
wh_…, webhook events evt_…, API keys bs_live_… and
webhook secrets whsec_…. Flows, groups and numbers keep small integer ids — they
are account-scoped objects you create, not records that accumulate.
⚠ Opt-out policy
Bodek SMS will not stop sending messages because a recipient sent an
opt-out message. A reply of STOP, UNSUBSCRIBE,
CANCEL or any other opt-out keyword is recorded and pushed to you as a
message.opt_out webhook event. It does not suppress that recipient, cancel
messages already queued to them, or send them any reply. Delivery stops only if and when
Bodek administration decides to stop delivery.
The company integrating with Bodek SMS is responsible for receiving these
webhooks and stopping delivery. Subscribe an endpoint to message.opt_out,
add the recipient to your own suppression list as soon as the event arrives, and stop sending
to them.
Violation of this rule can result in suspension of the Bodek SMS service.
Set this up before you send at scale: create a webhook endpoint, then read the full policy, the keyword lists and the reconciliation endpoint in SMS Webhooks → Opt-out policy.
Scope optouts:read. The record of everyone who asked you to stop — reconcile it
against your suppression list on a schedule, so an event your server missed is still caught.
It blocks nothing.
Rate limits
Each key has a per-minute request limit (default 30/min; set when you create
the key). Over it you get 429 rate_limited with a Retry-After header.
Each key also has a per-day message limit (rolling 24 hours); a send that would
pass it gets 429 daily_key_limit.
Messages can be sent to US and Canada numbers only (premium-rate and Caribbean
area codes excluded). Other numbers are refused with 400 unsupported_destination.
Separately, the account has a daily send allowance. Sends past it are rejected
unless the account has pay-as-you-go enabled (then they're metered up to a
spending cap). See Send a message for how rejections appear
(rejected/reason, or a 402 daily_limit_reached when all
recipients are rejected).
Health
No scope, but a valid key is required.
curl https://sms.bodek.us/api/v1/health -H "Authorization: Bearer bs_live_…"
{ "ok": true, "service": "sms", "version": "v1", "time": "2026-09-24T00:00:00+00:00" }
List numbers
Scope numbers:read. The numbers you can send from: the shared sending pool
(available to every account with SMS access) plus any group-dedicated number assigned to your
account. A key bound to one number returns just that number.
curl https://sms.bodek.us/api/v1/numbers -H "Authorization: Bearer bs_live_…"
{
"ok": true,
"numbers": [
{ "id": 12, "number": "+15551234567", "display": "(555) 123-4567", "label": "Front desk",
"online": true, "shared": true, "group": false }
]
}
For one number, with the reason it isn't usable when it isn't, see Is a number live?
Is a number live?
Scope numbers:read. Answers one question: can this number carry traffic right
now? GET /v1/numbers/{id}/status is the same endpoint under a longer name.
The path takes either the number's id or the phone number itself. Because a
+ is awkward in a URL, all four of these ask about the same number:
curl https://sms.bodek.us/api/v1/numbers/12 -H "Authorization: Bearer bs_live_…"
curl https://sms.bodek.us/api/v1/numbers/5551234567 -H "Authorization: Bearer bs_live_…"
curl https://sms.bodek.us/api/v1/numbers/15551234567 -H "Authorization: Bearer bs_live_…"
curl -g "https://sms.bodek.us/api/v1/numbers/+15551234567" -H "Authorization: Bearer bs_live_…"
{
"ok": true,
"number": {
"id": 12,
"number": "+15551234567",
"display": "(555) 123-4567",
"label": "Front desk",
"online": true,
"shared": false,
"group": true,
"live": true,
"state": "live",
"reason": "The number is checked in and can send and receive.",
"last_seen_at": "2026-10-26T16:49:30+00:00",
"seconds_since_seen": 14,
"online_window_s": 90
}
}
| Field | Description |
|---|---|
live | The answer. true only when the number is active, verified, and its phone has checked in inside the online window. |
state | Why, in one word: live, offline (nothing has checked in lately), unverified (the number isn't verified yet) or inactive (the number is turned off). |
reason | The same thing in a sentence you can show a user. |
online | Checked in recently. Same as the field in List numbers. |
last_seen_at | Last check-in (UTC, ISO 8601), or null if it has never checked in. |
seconds_since_seen | Age of that check-in in seconds, or null. |
online_window_s | How recent a check-in has to be to count as online (90 seconds today). Read it rather than hard-coding it. |
shared, group | shared: from the common sending pool. group: dedicated to your account for group texting. |
Offline is not the same as broken. A message sent to an offline number is
queued, not refused, and goes out when the number checks back in — so use live
to decide whether to expect an immediate send, not whether to send at all.
A number that isn't yours returns 404 not_found, and so does one that never
existed — the API doesn't say which. A key bound to a single number can only ask about that
number.
Check several at once
Up to 100 ids or phone numbers in one call. The answers come back in the order you asked,
each with the asked value echoed so you can line them up, and
found: false for anything you can't use.
curl -X POST https://sms.bodek.us/api/v1/numbers/status \
-H "Authorization: Bearer bs_live_…" -H "Content-Type: application/json" \
-d '{"numbers": [12, "+15551234567", "5559999999"]}'
{
"ok": true,
"numbers": [
{ "asked": "12", "found": true, "id": 12, "number": "+15551234567", "live": true, "state": "live", … },
{ "asked": "+15551234567", "found": true, "id": 12, "live": true, "state": "live", … },
{ "asked": "5559999999", "found": false, "live": false, "state": "unknown",
"reason": "No number you can use matches that id or phone number." }
]
}
Polling every 30 seconds is plenty: a phone checks in well inside the 90-second window, and the per-minute rate limit is shared with the rest of your calls.
Send a message
Scope messages:send.
| Field | Description | |
|---|---|---|
to | required | A phone number, or a list of up to 100. |
body | required | Message text (up to 1,600 characters). May be "" when media is sent. |
media | optional | Up to 5 attachments, sent as one picture message (MMS): [{"content_type": "image/jpeg", "data": "<base64>", "name": "menu.jpg"}]. Images, video, audio and vCards; up to 10 MB each before encoding. Images are shrunk to fit an MMS; video/audio must be under 1 MB. |
from | optional | A number id or E.164 to send from — any number in the shared pool or your group-dedicated number. Defaults to the pool. Ignored (forced) for a bound key. |
client_ref | optional | Your own reference, echoed back (≤ 80 chars). |
ttl | optional | Seconds the message stays queued before it expires (60–604800). |
idempotency_key | optional | See Idempotency (or send the Idempotency-Key header). |
curl -X POST https://sms.bodek.us/api/v1/messages \
-H "Authorization: Bearer bs_live_…" \
-H "Content-Type: application/json" \
-d '{
"to": "+15551234567",
"body": "Your table is ready!",
"client_ref": "order-8412"
}'
Returns 202:
{
"ok": true,
"messages": [
{ "id": 5567, "direction": "out", "phone": "+15551234567", "status": "queued",
"segments": 1, "client_ref": "order-8412", "created_at": "2026-09-24T00:00:00+00:00" }
]
}
Sending to a list of to numbers queues one message per distinct number.
Billing limits. If the account is over its daily send allowance and pay-as-you-go
is off, recipients are rejected. When some go through and some don't, the response is still
202 but adds rejected (a count), reason
(limit_reached, metered_cap_reached, number_limit_reached or paused) and a human message.
If every recipient is rejected, the call returns
402 daily_limit_reached with the
reason — enable pay-as-you-go to send beyond the daily allowance.
Pictures & attachments
Messages carry a media list (empty for plain texts). Received pictures appear on incoming messages the same way.
"media": [
{ "id": 88, "type": "image/jpeg", "size": 184220, "width": 1280, "height": 960,
"name": "menu.jpg", "url": "https://sms.bodek.us/api/v1/media/3f9c…" }
]
Scope messages:read. Downloads the file with the same Bearer key. Add ?download=1 to force a file download. Attachments are kept for 180 days.
Idempotency
To make a send safe to retry, set an Idempotency-Key header (or an
idempotency_key field), up to 80 characters. A repeat within 24 hours with the same
key returns the same messages instead of sending again — so a network timeout and retry
never double-texts a customer.
curl -X POST https://sms.bodek.us/api/v1/messages \
-H "Authorization: Bearer bs_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-8412-confirm" \
-d '{ "to": "+15551234567", "body": "Your table is ready!" }'
List messages
Scope messages:read. Query parameters: direction
(in/out), status, phone,
number_id, group_id, source, client_ref,
purpose, read=1, created_after,
created_before, sent_after, sent_before (ISO-8601 or
unix seconds), since_id, before_id, limit (default 50,
max 200).
Everything a platform needs to reconcile its traffic — both numbers, the text, the segment count, which key sent it and every timestamp — is on each message. See Pulling message details for the full field list and worked queries.
curl "https://sms.bodek.us/api/v1/messages?direction=in&limit=20" \
-H "Authorization: Bearer bs_live_…"
{ "ok": true, "messages": [ … ], "next_before_id": 5540 }
Page backwards with before_id, or poll new messages with since_id.
Both take the seq value, not the msg_… id.
Get a message
Scope messages:read. Takes the msg_… id or the row id. Delivery goes
queued → sending → sent → delivered, or ends in failed,
expired or cancelled; read_at is filled in when the
handset returns a read report (MMS/RCS only — plain SMS has none).
curl https://sms.bodek.us/api/v1/messages/msg_af6d1cbbb042d08e5ddeef055306fd5a -H "Authorization: Bearer bs_live_…"
{ "ok": true, "message": {
"id": "msg_af6d1cbbb042d08e5ddeef055306fd5a", "seq": 5567,
"direction": "out", "from": "+15551230000", "to": "+15557654321", "number_id": 12,
"body": "Your table is ready!", "status": "delivered", "source": "api",
"segments": 1, "attempts": 1, "client_ref": "order-8412", "api_key_id": 31, "error": null,
"created_at": "…", "sent_at": "…", "delivered_at": "…", "read_at": null, "expires_at": "…",
"media": [],
"delivery": { "state": "delivered", "terminal": true, "read": false, "bounced": false }
} }
Prefer webhooks to polling. Every one of these transitions — including
bounced for a permanent rejection and read for a read receipt — is
pushed to you as it happens; see
Delivery status events.
Scope webhooks:read. Every webhook event we raised about this message, to which
endpoint, with the payload sent and the response we got — the delivery audit trail for one
send.
Cancel a message
Scope messages:send. Cancels a message that is still queued; once it's
handed to a phone it can't be recalled (409 not_cancellable).
curl -X DELETE https://sms.bodek.us/api/v1/messages/5567 -H "Authorization: Bearer bs_live_…"
Webhooks & events
Instead of polling, let Bodek SMS push to you. An endpoint is a URL of yours plus a subscription list; every payload is signed with that endpoint's secret.
curl -X POST https://sms.bodek.us/api/v1/webhooks \
-H "Authorization: Bearer bs_live_…" -H "Content-Type: application/json" \
-d '{
"name": "Production listener",
"url": "https://your.app/hooks/bodek-sms",
"events": ["message.received", "message.opt_out", "message.delivered", "message.bounced"]
}'
| Family | Events |
|---|---|
| Inbound | message.received, message.opt_out, message.opt_in, message.help, message.keyword |
| Delivery status | message.queued, message.sending, message.sent, message.delivered, message.read, message.failed, message.bounced, message.expired, message.cancelled |
| Flows | flow.run.started, flow.run.step, flow.run.input, flow.run.completed, flow.run.expired, flow.run.stopped, flow.run.error, flow.updated |
Subscribe to exact names or to a family (message.*, flow.*,
*) — so an endpoint can receive opt-outs only and nothing else.
Each endpoint can also replace the opt-out / opt-in / help keyword lists with its own.
GET /v1/webhooks/events returns the catalogue at run time.
Everything else — the payload envelope, signature verification in PHP/Node/Python, per-endpoint keyword lists, the retry schedule, the delivery log and the full opt-out policy — is in SMS Webhooks. Manage endpoints in the console at SMS webhooks.
Groups
A group lives on one number; a text from a member is forwarded to the others. Read your groups
with groups:read, broadcast with messages:send, and (optionally) manage
them with groups:write.
Groups need a dedicated number. Unlike one-off sends (which use the shared pool), a group must be hosted on a number specifically assigned to your account. Creating a group on a shared/pool number is rejected — request a dedicated number first.
# One message to everyone in the group:
curl -X POST https://sms.bodek.us/api/v1/groups/7/messages \
-H "Authorization: Bearer bs_live_…" \
-H "Content-Type: application/json" \
-d '{ "body": "Practice is cancelled tonight." }'
With groups:write you can also create groups and manage members:
curl -X POST https://sms.bodek.us/api/v1/groups \
-H "Authorization: Bearer bs_live_…" \
-H "Content-Type: application/json" \
-d '{
"name": "U12 Team",
"number_id": 12,
"members": [ { "name": "Coach", "phone": "+15551230001", "admin": true } ]
}'
Calls
Each number is a real phone. When someone calls it, the phone applies your call rules (set on sms.bodek.us → Calls): let it ring, forward it to your number, send it to voicemail, or hang up — by caller and time of day. Any of these can also text back by starting your missed-call flow. The phone can't talk or listen on a call; menus happen by text.
Query: number_id, limit (≤ 200), before_id (paging). Needs calls:read.
{"ok": true, "calls": [{
"id": 81, "number_id": 12, "number": "+15551230000", "direction": "in",
"caller": "+15557654321", "hidden": false,
"outcome": "declined", // missed | declined (forwarded / voicemail) | hung_up | answered | silenced | placed | failed
"action": "decline", "rule_id": "r_3f9a01bc", "text_back": true, "duration_s": 0,
"flow_session_id": 431, // the text-back run, if one started
"started_at": "2026-09-25T14:03:11+00:00", "ended_at": "2026-09-25T14:03:11+00:00"
}]}
Flows (text menus)
A flow is a text conversation on one of your numbers: menus, questions, API calls mid-chat, branches, staff alerts. It starts on a missed call, a keyword, any text, or from the API, and it can be built and managed entirely over the API — same format and same validator as the editor on sms.bodek.us. Flows need a number dedicated to your account.
# Text a flow to someone now (e.g. an appointment confirmation menu):
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"}}
# Later: where is the conversation and what did they answer?
curl https://sms.bodek.us/api/v1/flows/runs/431 -H "Authorization: Bearer bs_live_…"
→ {"ok": true, "run": {"id": 431, "status": "done", "waiting_on_step": null,
"vars": {"name": "Ann", "appt": "Tue 3pm", "confirm": "yes"}, …}}
vars become {{name}} values in the flow's messages. Run
status: active (waiting for a reply), done,
expired, stopped, error. Needs
flows:read / flows:run, and flows:write to build or
change one. Flow texts count toward your daily message allowance like any send.
The full reference — the definition format, every step type, validation, activation rules, runs, API steps and limits — is in SMS Flows API.
No keyword is reserved for opt-outs, and a flow does not stop for anyone who replies STOP: see the opt-out policy.
Flows are text conversations. To control what a caller hears — answer the call, speak a keypad menu, forward it, take a voicemail — see SMS Call Flows. Every answered call there opens with a recording announcement that cannot be switched off.
System send (Bodek internal)
Bodek's own apps send 2FA codes and account notices through a separate, internal path
(POST /v1/system/send) authenticated by a shared server secret, not an API key.
It isn't available to customer keys. In-process callers use the Bodek\Sms\Internal
class instead. This is documented for completeness only.
Scopes
messages:send | Send messages and cancel queued ones. |
messages:read | Read messages and delivery status. |
numbers:read | List your numbers and check whether one is live. |
groups:read | Read groups and members. |
groups:write | Create and change groups. |
calls:read | Read the call log. |
flows:read | List flows and read their runs. |
flows:run | Start a flow for a number. |
flows:write | Create, change, activate and delete flows; stop runs. |
webhooks:read | List webhook endpoints and their delivery log, and read a message's events. |
webhooks:write | Create, change and delete webhook endpoints; send tests and retry deliveries. |
optouts:read | Read the opt-out record for your numbers. |
Choose scopes when you create a key. A call without the needed scope
fails with 403 insufficient_scope.
Permissions can be changed after a key exists. Open Change permissions
on the key at SMS API keys, tick what it should be allowed to do, and
save. The secret itself never changes — the same bs_live_… token keeps working, so
widening or narrowing an integration doesn't mean issuing a new key and redeploying. The new
permissions apply from that key's next request; nothing is cached. (The key is still only ever
shown once, at creation — that part can't be undone.) A revoked key can't be
re-permissioned; create a new one.
This is deliberately console-only: there is no API route for changing permissions, so a key that leaks can never widen what it is allowed to do.
Errors
Every error is {"ok": false, "error": {"code": "…", "message": "…"}}.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_number, invalid_body, invalid_vars, invalid_media, unsupported_destination, bad_request | The request didn't validate (unsupported_destination: only US/Canada numbers can be texted). |
| 401 | unauthorized, invalid_key | Missing, wrong, or revoked key. |
| 402 | subscription_inactive, daily_limit_reached | Plan doesn't include SMS, or all recipients were over the send allowance (with a reason). |
| 403 | insufficient_scope | The key lacks the required permission. |
| 404 | not_found | No such message, group, number, or route. A number you can't use is also 404. |
| 409 | not_cancellable, no_number, group_inactive, flow_inactive, flow_not_activatable, run_not_active, group_member, too_many_webhooks, not_retryable | Valid request, wrong state. |
| 400 | invalid_url, invalid_events | A webhook endpoint's URL is not an https address we will connect to, or its event list is empty/unknown. See Webhooks → Security. |
| 429 | rate_limited, daily_key_limit | Per-minute request limit or the key's per-day message limit; see Retry-After. |