API reference
One key, one endpoint, one signed webhook.
Everything /v1 serves today, taken from the code that serves it. What is not built yet is listed at the bottom rather than left for you to discover.
Read the last section first if you are evaluating us. Pairing a real number, sending, and receiving all run in production — a message reaches a handset and a reply comes back. What is still missing is listed at the bottom, and it is specific: what waits on this deployment's own Meta and Stripe setup. The home page draws the same line.
Base URL
https://sendbu.com/v1. There is no api. subdomain: /v1 is served by the same app that serves this page. Every request and response body is JSON — including a path that is not an endpoint, /v1 itself among them, which answers 404 not_found in the error envelope below.
The same reference, as files tools read: OpenAPI for code generators, a Postman collection, and a JavaScript client with no dependencies — new Sendbu(key).idempotent('order-1').post_messages({ … }).
Authentication
Every /v1 request carries an API key as a bearer token:
Authorization: Bearer sk_live_...You mint keys yourself in the panel, under Keys. The secret is shown once, at creation; we store only a hash of it, so a lost key is replaced rather than recovered. Revoking a key takes effect on the next request.
A request with no key, a malformed header, an unknown key, or a revoked one answers 401 with unauthorized. A valid key belonging to a suspended account answers 403 with account_suspended — which is a different thing and asks you for a different repair; see the error table.
A key can do everything unless it was narrowed when it was made. Its scopes name an area and an access — messages, channels, contacts, campaigns, templates (which covers triggers), webhooks and auto-replies, each :read or :write — and * is all of them. read answers GETs; write answers the rest and includes read. Conversations and media are part of messages. A request outside a key's scopes answers 403 forbidden naming the required_scope; the MCP tools are held to the scope of the endpoint each one stands for. Only an account owner can make a * key — the one /v1/clients and /v1/branding need. A full-access key an admin makes carries every area by name instead.
Rate limits
An organization may make 300 requests a minute to /v1 and /mcp together, counted across all of its keys — minting a second key does not buy a second budget. Every tools/call in an MCP batch past the first counts as a request of its own. Past the limit a request answers 429 rate_limited with a Retry-After header in seconds, and the same number in the body as retry_after_seconds; wait that long rather than retrying at once. Every other 429 — a number's daily new-conversation limit, the per-minute send limit, a trigger's 200 deliveries a minute — carries the header the same way.
OPTIONS on any /v1 path answers 204 with an Allow header listing the methods it serves.
Sending a message
POST/v1/messages
Takes channel_id, to (E.164, e.g. +15551234567, or a group id from GET /v1/channels/:id/groups), type, and one field named after the type. Unknown fields are rejected rather than ignored, and so is a field for another type.
text—text.body, 1 to 4096 characters.image,video—urland an optionalcaption(up to 1024).audio—url. No caption; WhatsApp shows none.document—url, optionalcaptionandfilename(what the recipient sees it called).location—latitude,longitude, optionalnameandaddress.contact—nameandphone(E.164); we build the contact card.poll—question, 2 to 12options, andselectable_count(how many one person may pick, 1 by default). Not on official numbers. Votes arrive aspoll.vote, and the message carries the runningresults.template— an approved template, official numbers only, and the one thing they may send outside the 24-hour window:name,language, andbody_parametersfor its {{1}}, {{2}}… or Meta's owncomponents.interactive— official numbers, inside the 24-hour window. Abody.text, optionalheader.textandfooter.text, and atype:buttonswith up to three{ "id", "title" };listwith thebuttonthat opens it andsectionsofrows(ten in all, each{ "id", "title", "description"? });urlwith{ "text", "url" }; orflow, a WhatsApp Flow built in Meta's Flow Builder, withflow_id,cta, and optionally the firstscreen, itsdataand"mode": "draft"; orcarousel, 2 to 10cardspeople swipe through, each{ "image" | "video", "text", "button": { "text", "url" } }, all with the same kind of picture.reaction—message_id, our id for a message in this same conversation, andemoji; an empty string takes a reaction back.
A file is fetched from its url, which must be https and reachable without signing in; it is not uploaded to us and we do not keep it. The message row's body is the caption, or a short description such as Document: invoice.pdf
, so the inbox and your webhooks still have a sentence to show. A channel that cannot send a type answers 422 capability_unsupported before anything is queued.
Requires an Idempotency-Key header. Answers 202 with id, status and channel_id.
curl https://sendbu.com/v1/messages \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: order-8842-shipped" \
-H "Content-Type: application/json" \
-d '{ "channel_id": "6b1f0c4e-9a2d-4f77-bd31-0c5a7e2f9a10",
"to": "+15551234567",
"type": "text",
"text": { "body": "Your order has shipped." } }'
< 202 Accepted
{ "id": "0f9c7a55-3d84-4b1e-9a60-27ce1f0b4d93",
"status": "queued",
"channel_id": "6b1f0c4e-9a2d-4f77-bd31-0c5a7e2f9a10" }202, not 200
200 would claim the message was delivered. It has not been: it has been accepted and queued, and the channel may still be reconnecting. The true outcome arrives later, as a webhook. A message's status is one of scheduled, queued, cancelled, sending, sent, delivered, read, failed, received.
A channel that is disconnected or logged_out is refused up front with 409 channel_not_connected rather than accepted — a message that can never be sent should not be queued. A channel that is pairing or reconnecting is accepted, and the message waits for the socket.
Stickers, video notes and events
"type": "sticker", "sticker": { "url": "https://…/s.webp" } sends a WebP as a sticker. Add "note": true to a video to send it as a round video note where the number supports one; elsewhere it goes as an ordinary video. "type": "event", "event": { "name", "start_time", "end_time", "description", "location" } sends an invitation people can answer — on numbers paired through the multi-device connection only; others answer 422 capability_unsupported.
People with a WhatsApp username
Somebody who takes a WhatsApp username may hide their number. On an official number they then arrive with a user id instead — "from": "US.13491208655302741918" — and the webhook carries user_id and username when WhatsApp sends them. Send to that id as to like a number. When a message comes with both, we keep the pair on the contact, so a later message with the number hidden stays in the same conversation.
Replying to a message, and mentions
Add "reply_to": { "message_id": "…" } with the id of a message in the same conversation on the same channel, and WhatsApp shows your message quoting it. A message that never reached WhatsApp cannot be quoted. In a group, add "mentions": ["+15551234567"] and write @15551234567 in the text: WhatsApp highlights the person and tells them.
Sending it later
Add send_at, an ISO 8601 time with an offset — 2026-09-20T14:00:00+01:00. The response is 202 with "status": "scheduled" and the time echoed back as scheduled_at.
The offset is required rather than assumed. 2026-09-20T14:00:00 is two o’clock somewhere, and the somewhere is what decides whether a reminder lands before or after the thing it reminds about; refusing the ambiguous form costs you one character.
scheduled is its own status and not queued, because queued honestly reads as “any moment now”. A time in the past is refused — almost always an offset got wrong, and sending immediately is the one outcome you cannot take back — and so is one more than 90 days ahead.
The allowance is taken when the message is accepted, not when it sends. Otherwise a scheduled batch would book against a limit nothing had reserved and only fail days later.
Retrying with the same Idempotency-Key is safe and does not move the time: the delay is computed from the stored message, not from the request, so a flaky connection cannot push a reminder past the thing it was reminding about.
POST/v1/messages/:id/cancel
Cancels a scheduled message and gives the allowance back. Answers the message with "status": "cancelled".
cancelled is its own status rather than failed, which would be a lie about the thing a status most needs to get right: failed means we tried and WhatsApp would not take it, and you would go looking for a fault that does not exist.
Only a scheduled message can be — anything else answers 400 naming the status that stopped it. It is terminal, and there is no un-cancel: by the time anybody asks, the time it was due for has often passed, and a send that quietly goes out late is worse than one that does not go at all. Sending it again is one POST.
The allowance is credited back to the month the message was accepted in, which for something scheduled forty days out is not this one.
Idempotency-Key
Required, not optional. A request without one answers 400 invalid_request.
The key is unique per organization. A retry carrying the same key returns the existing message — the same id, and whatever status it has reached — and sends nothing further. So a timeout on your side never becomes two messages on your customer's phone. Keys are trimmed, so a stray newline in a header does not create a second message.
A retry gets the original message even if the request changed or the channel has since disconnected: the answer's channel_id is the one that message was sent from, not the one in the retry. If a send answers 503 capacity_unavailable, retry it with the same key — the message may already be stored, and the retry queues it.
Keys may not start with a prefix our own messages use — wa_in:, campaign:, flow:, csat:, autoreply:, verify:, chatwoot:, typebot:, dify:, flowise:, ai:, call: or test: (in any case). Such a key answers 400 invalid_request.
Reading messages
The pull side of what webhooks push. Every endpoint here is a read: nothing is queued and nothing is changed. A message id belonging to another organization answers exactly like an id that never existed — 404 — because telling you a message exists but is not yours is telling you a message exists.
GET/v1/messages
One page of this organization's messages, newest first. Filters: channel_id, status (one of scheduled, queued, cancelled, sending, sent, delivered, read, failed, received), direction (inbound or outbound) and contact — the other party in E.164, which is what turns this endpoint into "read one conversation" — and q, 2 to 200 characters of text to find in the message. Pages with starting_after; see paging.
Each message carries scheduled_at: when it was asked to go, or null for “as soon as possible” and for anything received. It stays after the message went, beside created_at (when we accepted it).
limit is 1 to 100 and defaults to 25. A value that is not a whole number in that range is refused rather than rounded or defaulted, because quietly serving 25 rows hides the bug until somebody wonders why their pagination stopped early.
GET/v1/messages/:id
One message. Answers 404 for an id this organization does not own.
PATCH/v1/messages/:id
Changes the words of a text message you sent, { "text": { "body": "…" } }, within WhatsApp's 15 minutes. Answers 202: the open session makes the change and the message then carries edited_at and its new text.body.
DELETE/v1/messages/:id
Deletes a message you sent for everyone in the chat, within two days of sending. Answers 202; the message then carries deleted_at and keeps its words here for your records. Official numbers answer 422 capability_unsupported, and a number that is not connected 409 channel_not_connected.
GET/v1/assignment
How conversations are handed out and the answer-time target: { "mode": "least_busy" | "off", "sla_minutes": 30 | null }.
PUT/v1/assignment
With least_busy, a conversation nobody holds goes, when a message arrives in it, to the member with the fewest open conversations. With sla_minutes, a conversation whose newest message is the customer's and older than that is marked overdue in the inbox and announced once as conversation.overdue.
POST/v1/verifications
Sends a six-digit code over WhatsApp, for sign-ups and logins: { "channel_id", "to": "+44…", "template"?: { "name", "language" } }. An official number needs the name of an approved authentication template (Meta allows codes only in those); a session number sends a plain line. Answers 201 with id, message_id and expires_at — ten minutes. Five codes an hour go to one number. We keep only a hash of the code.
POST/v1/verifications/:id/check
{ "code": "123456" } answers 200 with { "valid": true | false, "tries_left" }. A right code works once; five wrong ones end it; an expired or used one is 404.
GET/v1/clients
For an agency running WhatsApp for several businesses: its client accounts, each { "id", "name", "plan", "channels", "messages_this_month", "created_at" }. A client is a whole account of its own — numbers, keys, contacts and limits — so no client sees another's customers. Needs a key with every scope (*).
POST/v1/clients
{ "name": "Acme Dental" } creates a client account on the agency's plan and answers 201 with client and api_key, the client's first key, shown once. Use it to connect the client's number and send for them. A client cannot have clients of its own.
The plan's monthly message allowance is one pool for the agency and all of its clients: a message any of them sends counts against it, and once it is spent every account in the group answers 402 quota_exceeded until the month resets. Each account's Usage screen shows the whole pool: a client's says it is shared with the agency and how many of the pool's accepted messages came from that client; the agency's says how many client accounts share it and, once a client has sent, how many came from the agency itself. A client's screen offers no plan change — its plan and allowance come from the agency.
GET/v1/branding
The name and logo the panel shows instead of ours: { "branding": { "name", "logo_url" } | null }. Set on an agency, its clients see it too.
PUT/v1/branding
{ "name": "Acme Messaging", "logo_url": "https://…/logo.png" } (name up to 40 characters, logo optional and https); null goes back to ours. Needs a key with every scope (*).
GET/v1/csat
The satisfaction survey: { "settings": { "enabled", "question" }, "last_30_days": { "responses", "average" } }.
PUT/v1/csat
Takes { "enabled": true, "question": "How did we do? Reply 1 to 5." }. When a conversation is closed in the inbox, the person is sent the question; a lone 1 to 5 from them in the next day is recorded as their answer and nothing else replies to it. Never in a group.
GET/v1/flows
Menu flows, { "data": [{ "id", "name", "channel_id", "triggers", "steps", "enabled" }] }. A message that is one of a flow's triggers starts it: the first step is sent with its options numbered, and the answer — the number or the option's words — leads to the step the option names. A step with no options ends the flow; so does an option whose next is null, handing the conversation to your team. While a flow answers, the automatic replies and bots stand aside.
POST/v1/flows
{ "name", "channel_id", "triggers": ["menu"], "steps": [{ "id": "start", "text": "How can we help?", "options": [{ "label": "Opening hours", "next": "hours" }] }, { "id": "hours", "text": "9 to 5.", "options": [] }] }. An option that leads to a step that does not exist is refused.
PUT/v1/flows/:id
Replaces the flow, whole, with the same shape.
DELETE/v1/flows/:id
Removes it. 204.
GET/v1/saved-replies
Replies your team sends often, { "data": [{ "id", "shortcut", "body", "updated_at" }] }. In the inbox, type / and the shortcut to insert one.
POST/v1/saved-replies
Takes { "shortcut": "opening-hours", "body": "We are open 9 to 5." }. The same shortcut again replaces the text.
DELETE/v1/saved-replies/:id
Removes one.
GET/v1/notes
The notes on one conversation, ?channel_id=…&contact=+15551234567, oldest first.
POST/v1/notes
Leaves a note on a conversation for your team, { "channel_id", "contact", "body" }. It is never sent to the person.
GET/v1/media/:id
A file somebody sent to one of your numbers, by the media_id its message and its webhook carry. Answers the bytes, with the type WhatsApp reported. Photos, video, audio and PDFs are served inline; anything else as a download, whatever type the sender claimed, because the sender chose it. Another organization's id answers 404, as does a file we no longer hold.
Files over 25 MB are not kept; the message still arrives, with the file's field carrying unavailable and the reason in place of media_id. So does one WhatsApp would not hand over.
The wrong method
A verb a path does not serve answers 405 with the JSON envelope like everything else, and an Allow header listing what would work — so a client that guessed can read the answer rather than parse an empty body. It used to answer 405 with no body, no content type and no Allow at all, which broke both the promise above and the one HTTP makes.
The code is invalid_request rather than one of its own: a wrong method is a malformed request, and the part worth branching on is the Allow header, which HTTP already defines for exactly this.
Why a message failed
Every message carries failure_code and failure_message, both null until a send actually fails. The message is a sentence for a person to read; the code is the part to branch on, and these are all of them. They were returned by the API before they were written down here, which is a field with undocumented values — not useful to anybody.
| code | what happened, and whether sending again helps |
|---|---|
channel_reconnecting | The channel dropped and was still reconnecting two minutes later. Nothing was delivered, so sending again is safe — and worth checking the handset for, because a channel down that long usually means the phone is offline or the session was linked somewhere else. |
retries_exhausted | A connected channel refused the send on every attempt. Nothing was delivered, so sending again is safe, but expect the same answer until whatever refused it changes. When no attempt even reached WhatsApp the code reads retries_exhausted_unsent instead, and the allowance is given back. |
delivery_unconfirmed | We called WhatsApp and never recorded what came back, so we cannot tell you whether it arrived. Deliberately not retried: a duplicate is a spam signal and spam signals get numbers banned. This is the one code where sending again is a decision for a person, not a client. |
account_suspended | The organization was stopped before this message went out. Queued messages are failed rather than held, so restoring the account does not fire a burst of hours-old messages nobody re-approved. |
not_found | The channel was deleted between accepting the message and sending it. |
account_restricted | WhatsApp took the message and then refused it, because the number is restricted from starting new conversations — WhatsApp’s error 463. Nothing was delivered. The channel is marked restricted at the same moment, and first contacts are refused up front until it lifts; replies to people who wrote first carry on. |
refused_by_whatsapp | WhatsApp took the message and then refused to deliver it, for a reason other than a restriction. Nothing reached the recipient. Three of these on one number inside an hour are read as a restriction WhatsApp did not announce, and the channel is treated as restricted for a day. |
channel_restricted | Not sent. It was queued before the number was restricted, it was to somebody who had never written to the number, and sending it would have been one more attempt counted against it. Nothing left. |
opted_out | Not sent. A campaign message, a follow-up or an abandoned-cart reminder was waiting when the person opted out of marketing. Nothing left. |
campaign_paused | Not sent (the message reads cancelled): its campaign was paused while this message waited. Resuming the campaign sends this person a fresh message. Nothing left. |
campaign_cancelled | Not sent (the message reads cancelled): its campaign was cancelled while this message waited. Nothing left. |
campaign_message_not_sent | A campaign follow-up that was not sent (it reads cancelled) because the campaign's first message to this person never went — it failed, was cancelled or was withdrawn. Nothing left, and the allowance was given back. |
marketing_opted_out, marketing_limit, spam_rate_limited, country_restricted, undeliverable, pair_rate_limited, template_paused, template_disabled, template_category_violation, meta_experiment | Official numbers: Meta's own reason, named. A person who stopped this business's marketing is tagged “marketing_opt_out” and left out of every campaign; account_restricted or spam_rate_limited from Meta pauses new conversations on the number for a day. |
Anything else in this field is the error code from the provider call itself — the same vocabulary as the table further down this page.
GET/v1/conversations
One row per contact this organization has exchanged a message with, newest first, each carrying the last message and the unread count. Filters on channel_id. limit is 1 to 100 and defaults to 25, refused outside that range like the messages list. There is no cursor here — the answer is data alone, the newest limit conversations: the row count is contacts, not messages, and /v1/messages is where the volume is.
Paging
A paged list — GET /v1/messages and GET /v1/contacts — answers data, has_more and next_cursor. Pass next_cursor back as starting_after for the next page, and stop when has_more is false. Both also take the cursor as cursor, an alias kept for clients already sending it; the two at once must agree. A limit outside a list's range is refused with 400, never clamped.
It is a cursor and not an offset, and the difference matters here more than usual: this list is ordered newest first and is written to constantly — every send, every status change, every message that arrives. Under OFFSET, a row arriving while you page pushes everything below it down one, so page two re-reads a row page one already gave you. The cursor is <timestamp>|<id> in the open; there is nothing secret in it, and a cursor we cannot parse is refused rather than treated as the first page — silently restarting you at the top is an infinite loop that looks like working software. So is a channel_id filter that is not an id we issued: both answer 400 invalid_request. Messages written in the same millisecond — a campaign, a burst — are each served exactly once across pages.
Channels
A channel is one WhatsApp number. Creating one takes one optional choice — how the session is held, see POST /v1/channels below — and what it can do afterwards is on the channel itself, as capabilities.
A channel's status is one of disconnected, pairing, connected, reconnecting, logged_out, its capabilities are drawn from text.send, text.receive, media.send, location.send, contacts.send, reactions.send, groups.send, contacts.read, templates.send, polls.send, events.send, catalog.send, interactive.send, and its session_mode is one of direct, browser — the same value you create it with — or null for an official number, which no session holds.
Official numbers. A number on Meta’s Cloud API is added in the panel, through Meta’s own signup, not through this endpoint: Meta issues the credential to the business that signs up, and only its window can. Either a new number, or one already on the WhatsApp Business app, which keeps working on the phone as well (Meta calls this coexistence). Once added it is an ordinary channel here — the same sends, the same inbox, the same webhooks. Meta allows free text only to somebody who wrote in the last 24 hours; a send to anybody else answers 400 invalid_request with scope set to service_window_closed, before anything reaches Meta — send an approved template instead. It is on the pro plan, and appears in the panel once this deployment is connected to a Meta app.
GET/v1/channels
Lists this organization's channels. Answers 200 with { "data": [...] }.
POST/v1/channels
Takes an optional session_mode — direct, browser — and answers 201 with the channel, whose status begins as disconnected. An empty object, {}, or no body at all picks the default. Any other field is refused rather than ignored, so a request that believes it is choosing something it cannot finds out.
direct means we talk to WhatsApp ourselves, and is on every plan. browser means we keep a real browser open to WhatsApp Web for the number, which costs us a browser per number and so is on the pro plan. Neither is safer: what gets a number restricted is messaging people who never wrote first, and that is the same on both. A mode your plan does not include answers 400 invalid_request naming the mode and the plan.
It used to take a provider naming the implementation behind the channel. That was removed, and is still refused: the value was ours rather than yours. session_mode is the choice in your words, and what a channel can actually do is still on the channel as capabilities — branch on that.
GET/v1/channels/:id
Answers 200 with the channel, or 404 not_found. A channel belonging to another organization answers 404 too.
DELETE/v1/channels/:id
Answers 204 with no body. A channel that still has message history is refused rather than deleted.
POST/v1/channels/:id/connect
Starts a pairing attempt. Answers 202: nothing has connected yet, and the QR code comes from a worker's socket a moment later. Poll the challenge endpoint below for it.
GET/v1/channels/:id/challenge
Answers 200 with { "status": ..., "challenge": ... }. The challenge is null before the first QR, between one code expiring and the next, and after pairing ends — that is not a failure signal. Only status is terminal: connected means done, logged_out or disconnected mean the attempt failed.
A challenge carries type (qr or pairing_code), value, sequence and expires_at. The sequence increments on each refresh and restarts at 1 on every connect, so forget the sequence you remembered whenever you call connect. Impose your own polling timeout: a channel stuck at pairing with no challenge will not time itself out.
POST/v1/channels/:id/disconnect
Closes the socket and leaves the channel registered. Answers 200 with the channel.
GET/v1/channels/:id/groups
The WhatsApp groups this number is in, as its session last reported them: { "data": [{ "id": "120363…@g.us", "subject": "…", "participants": 12, "updated_at": "…" }] }. Send to one by passing its id as to on POST /v1/messages; a group the number is not in is refused. A group message is never a first contact, so the first-contact limits do not count it — but the per-minute limit does. Messages said in a group arrive as message.received with "group": { "id": "…@g.us" } and from set to the member who said them; automatic replies and opt-outs never act on them. Official numbers have no groups.
POST/v1/channels/:id/groups
Creates a group or changes one the number is in, on the open session; answers 202. { "op": "create", "subject", "participants": ["+1…"] }, subject, description, leave, and add / remove / promote / demote with group_id and up to 20 participants. Only people who have written to this number may be put into a group — pulling strangers in is how numbers get reported. People who asked to join a group that needs approval are answered with approve / reject and their participants (they asked, so the rule above does not apply); { "op": "approval", "group_id", "on": true } makes joining by link wait for an admin, false lets the link admit anyone. Each request is announced as group.join_requested with group_id, from and action (requested, revoked, rejected).
POST/v1/channels/:id/chats
Housekeeping on one chat, { "contact": "+1…" | "…@g.us", "op" }: block, unblock, archive, unarchive, pin, unpin, mute (eight hours), unmute, unread, and on WhatsApp Business numbers label / unlabel with "label": "Paid", a label by the name the team sees on the phone. Answers 202; the phone shows it a moment later.
GET/v1/channels/:id/official-groups
The groups of an official number, from Meta: { "id", "to", "subject" }. Meta offers groups to Official Business Accounts only, up to 8 people each. Send to one with to set to its group:<id>; what people say in it arrives as message.received with group set.
POST/v1/channels/:id/official-groups
Done at Meta while you wait; answers 200 with Meta's result. { "op": "create", "subject", "description"?, "approval"?: true } answers the new group's id, to and invite_link — nobody is added, people join by the link. With group_id: delete; invite_link ("reset": true for a new one); remove with up to 8 participants; approve / reject with the join_requests ids — each request arrives as group.join_requested carrying its join_request_id. A new group Meta has not finished making answers "pending": true and appears in the list a moment later.
GET/v1/channels/:id/approved-templates
An official number's templates as Meta holds them — { "data": [{ "name", "language", "status", "category", "components" }] }. status is Meta's: APPROVED, PENDING, REJECTED. Other numbers answer 422 capability_unsupported.
POST/v1/channels/:id/approved-templates
Submits one for review: { "name": "order_shipped", "language": "en_US", "category": "UTILITY", "components": [{ "type": "BODY", "text": "Your order {{1}} has shipped." }] }. components is Meta's own shape, passed through. Answers 202 with Meta's id and status; review takes minutes to a day.
DELETE/v1/channels/:id/approved-templates/:name
Deletes it at Meta, every language. 204.
GET/v1/channels/:id/integrations
The services this number's conversations are connected to: { "data": [{ "kind": "typebot" | "chatwoot", "enabled", "config", "hook_url"? }] }. Tokens are never printed back. Chatwoot's hook_url carries the secret that lets Chatwoot send from the number, so it is included only for a key with channels:write; a channels:read key gets the rest without it.
PUT/v1/channels/:id/integrations/:kind
typebot takes { "base_url": "https://typebot.io", "typebot_id": "…" } — the public id from the bot's Share page. Every message that is not in a group goes to the flow, and what it answers is sent back, through the same limits as any send; while it is connected, the automatic replies stand aside. Somebody who says STOP is not answered by it.
ai takes { "model": "gpt-4o-mini", "instructions": "…", "api_key": "…" } and optionally base_url for any OpenAI-compatible endpoint — OpenAI's own when left out. With your key, a model answers every message that is not in a group, given the last twenty messages and your instructions; like Typebot it stands in for the automatic replies and goes through the same limits. The key is stored sealed and never read back; leave it out of an update to keep it.
dify takes { "api_key": "app-…", "base_url"? } (Dify Cloud when left out) and flowise takes { "base_url", "chatflow_id", "api_key"? }: an agent you built there — one that answers from your own documents, say — answers the number the same way, and keeps its own memory of each conversation.
Any of these bots answers one conversation at most 20 times in 10 minutes. A person does not write that fast; two machines answering each other do, and a number sending hundreds of machine messages an hour is a number WhatsApp takes away. Past it the bot stays quiet until the window ends, and the messages still reach the inbox and Chatwoot.
chatwoot takes { "base_url", "account_id", "inbox_id", "api_token" } for an API inbox. Every message lands in that inbox, and the answer carries hook_url: paste it into the inbox's webhook URL, and what agents reply there is sent from the number, attachments included. The secret may also be sent as an X-Sendbu-Token header instead of ?token=; both work. api_token may be left out of an update to keep the stored one. Add "enabled": false to pause either without losing the settings.
The Chatwoot fields are strict: account_id and inbox_id are strings of 1 to 12 digits — "3", not 3 — read from your Chatwoot URL and the inbox's settings; base_url is at most 512 characters; api_token is 8 to 200 characters. Any other field is refused.
A stored api_key or api_token is kept only for the address it was entered for. An update that changes base_url (or Chatwoot's account_id) must send the key again, or it answers 400 invalid_request.
DELETE/v1/channels/:id/integrations/:kind
Disconnects it. 204.
GET/v1/channels/:id/catalog
The number's WhatsApp Business catalog, as last read: { "data": [{ "id", "name", "description", "price", "currency", "imageUrl", "url", "retailerId" }] }. Read each time the number connects and after every change. Send one with "type": "product", "product": { "product_id": "…", "body": "…" }.
POST/v1/channels/:id/catalog
{ "op": "create", "name", "description", "price": 12.5, "currency": "GBP", "image_url": "https://…" } adds a product; { "op": "delete", "product_ids": ["…"] } removes some; { "op": "refresh" } reads it again. Answers 202. WhatsApp Business numbers paired through the multi-device connection only; official numbers manage theirs in Meta's Commerce Manager.
POST/v1/channels/:id/communities
A community — a group of groups: { "op": "create", "subject", "description" }, or { "op": "link" | "unlink", "community_id": "…@g.us", "group_id": "…@g.us" } for a group the number is in. Answers 202; the new community appears among the groups.
GET/v1/channels/:id/link
A link that opens a chat with this number, ?text=… to have words already typed: { "url": "https://wa.me/…", "qr_svg", "button_html" }. People who arrive this way wrote first, so every answer is a reply rather than a cold contact.
GET/v1/channels/:id/newsletters
The WhatsApp Channels this number administers and may post to: { "data": [{ "id": "1203…@newsletter", "name", "role": "owner" | "admin" }] }. Send to one with its id as to, like a group. Its followers chose to follow it, so posts are not first contacts and no conversation limits apply.
POST/v1/channels/:id/newsletters
Takes { "invite_link": "https://whatsapp.com/channel/…" }. WhatsApp gives no list of the channels a number runs, so the open session looks this one up and keeps it only when the number owns or administers it. Answers 202; it appears in the list a moment later.
DELETE/v1/channels/:id/newsletters/:newsletterId
Stops posting to it from here. The channel itself is untouched.
GET/v1/channels/:id/profile
The number's WhatsApp profile as last read from its session: { "profile": { "name", "about", "hasPicture", "checkedAt" } | null }. It is read each time the number connects and after every change.
PUT/v1/channels/:id/profile
Takes any of { "name": "…", "about": "…", "picture_url": "https://…" } — a name up to 25 characters, an about line up to 139, a public JPEG — and answers 202: the change is made on the open session a moment later. A number with a name and a photo looks like a business rather than a stranger, and gets reported less. A number that is not connected answers 409 channel_not_connected; official numbers set their profile in Meta's Business Manager.
GET/v1/channels/:id/quiet-hours
When this number does not start new conversations: { "quiet_hours": { "timezone": "Europe/London", "from": "21:00", "to": "08:00" } | null }.
PUT/v1/channels/:id/quiet-hours
Takes { "quiet_hours": { "timezone", "from", "to" } }, or null for none. A message to somebody who has not written to the number, asked for inside these hours, is not refused: it comes back scheduled for when they end. Replies go at once.
GET/v1/channels/:id/proxy
Whether this channel connects through a proxy of yours, and where: { "proxy": { "scheme", "host", "port", "authenticated" } | null, "applies": "next_connect" }. The credentials are never printed back.
PUT/v1/channels/:id/proxy
Takes { "url": "socks5://user:pass@host:1080" } — http, https, socks5 or socks5h, a host and a port — and routes this number's WhatsApp session through it, so WhatsApp sees your address rather than our data centre's. The password is encrypted at rest. It applies the next time the channel connects: disconnect and connect it to switch now. A proxy that resolves inside our network is refused. Official numbers take none; Meta connects for them.
DELETE/v1/channels/:id/proxy
Removes it; the next connect goes direct.
GET/v1/channels/:id/calls
What this number does when somebody calls it: { "calls": { "reject": true, "message": "Please write to us here." } | null }. null lets calls ring on the paired phone. On an official number it works once calling is switched on for the number at Meta and the app subscribes to the calls webhook field; each call is announced as call.received.
PUT/v1/channels/:id/calls
Takes { "calls": { "reject": true, "message": "…" } }, or { "calls": null } to let calls ring. A rejected caller is sent the message, up to 1000 characters, through the same limits as any other send. Every call is announced as call.received, with whether it was rejected. Official numbers answer 422 capability_unsupported: Meta handles their calls.
POST/v1/channels/:id/status
Posts to the number's own WhatsApp status: { "text": "…" } up to 700 characters, or { "image": { "url": "https://…", "caption": "…" } }. It is shown to the people who have written to this number, the most recent thousand, and answers 202 { "audience": 412, "applies": "queued" }. A number nobody has written to answers 400; official numbers 422 capability_unsupported.
POST/v1/channels/:id/typing
Shows typing…
to one person — { "to": "+15551234567", "seconds": 5 }, 1 to 25 seconds, 3 by default — while your bot composes an answer. Answers 202: it is shown on the open session, and skipped rather than retried if the session is not open, because late is worse than never. Sends already show it for a moment on their own. A channel that is not connected answers 409 channel_not_connected; official numbers answer 422 capability_unsupported.
Webhooks
We POST JSON to an endpoint you register. The events that exist today are message.sent, message.failed, message.received, message.delivered, message.read, channel.status_changed, campaign.finished, campaign.paused, campaign.resumed, campaign.cancelled, poll.vote, status.posted, call.received, message.edited, conversation.overdue, group.join_requested, channel.meta_alert — a subscription naming anything else is refused at registration rather than stored and silently never delivered.
An endpoint only ever receives what it subscribed to, including events added after you registered it. This list grows. When it does, your existing endpoint keeps working and does not start receiving the new events — which is the promise, not an oversight: nobody should be paid in webhooks they did not ask for. To pick one up, add it with PATCH /v1/webhooks/:id, which keeps your signing secret and your delivery history. The panel has the same thing as Edit events
beside each endpoint.
Worth saying because it is the confusion this section was written out of: message.delivered and message.read arrived after the endpoints that exist today were registered, so the receipts were landing on the messages and firing no webhooks at all. Nothing was broken; the subscription simply had not been asked to include them.
GET/v1/webhooks
Lists your endpoints, newest first, as { "data": [...] }. Never includes a secret.
POST/v1/webhooks
Takes url (https, publicly resolvable) and events, a non-empty array drawn from the list above. Answers 201.
This is the only response that ever carries the signing secret, as secret (whsec_…). Store it then; no later read returns it. An organization may hold at most 20 endpoints.
PATCH/v1/webhooks/:id
Changes events, enabled, or both, and keeps the signing secret. Answers 200 with the endpoint.
This is how you pick up an event that did not exist when you registered. Without it the only way to change a subscription was to delete the endpoint and register a new one, which mints a secret your receiver does not have yet and takes the delivery history with it.
url is not patchable, deliberately. The secret was agreed for that address, and an endpoint whose address can change while keeping its secret is a redirect nobody would see. Register the new address and delete the old one. A body carrying url answers 400 invalid_request with field: url.
DELETE/v1/webhooks/:id
Answers 204. The endpoint's delivery history goes with it.
GET/v1/events
The same events as the webhooks, live, as Server-Sent Events — for a client that cannot expose a URL. Each arrives as event: message.received and a data: line with the JSON a webhook would carry. With curl: curl -N -H "Authorization: Bearer sk_live_..." https://sendbu.com/v1/events. It is best-effort: what happens while nobody is connected is not replayed, which is what webhooks and GET /v1/messages are for. Needs webhooks:read.
An organization may hold 20 streams open at once; the 21st answers 503 capacity_unavailable until one closes. A comment line is sent every 20 seconds as a heartbeat, and the key is checked again each time — a revoked key or a suspended account ends the stream. A stream ends after an hour whatever happens; both endings send a stream.closing event saying why, and a client simply reconnects.
GET/v1/event-destinations
Queues events are also sent to, for systems that read a queue rather than serve HTTP: { "data": [{ "id", "kind", "config", "events", "enabled", "last_error", "last_delivered_at" }] }. The credential is never read back.
POST/v1/event-destinations
An Amazon SQS queue, { "kind": "sqs", "queue_url": "https://sqs.eu-west-1.amazonaws.com/123456789012/sendbu", "access_key_id", "secret_access_key" }— a key allowed only sqs:SendMessage on that queue — or a RabbitMQ exchange through its management API, { "kind": "rabbitmq", "base_url": "https://rabbit.example.com", "vhost": "/", "exchange", "username", "password" }, routed by the event name. Or HubSpot, { "kind": "hubspot", "access_token": "pat-…" } — a private app token with the contacts and notes scopes — and every message received and sent lands as a note on the HubSpot contact with that number, created if there is none. Or a team chat, { "kind": "slack" | "teams", "webhook_url": "…" } — an incoming webhook — and messages received, sends that failed and calls arrive in that channel as a line each. Add events to take only some; empty takes all. Each message is the webhook body. Failures are retried with backoff and the last one is kept on the destination as last_error.
DELETE/v1/event-destinations/:id
Stops sending events there. 204.
POST/v1/webhooks/deliveries/:id/redeliver
Sends a delivery again, as a new delivery with the same event and payload — once you have fixed your endpoint, there is no need to wait for the next event. Answers 202 { "delivery_id" }. The Webhooks screen has the same button beside each failure.
What we send
POST https://your-app.example.com/hooks/sendbu
Content-Type: application/json
Sendbu-Signature: t=1757913600,v1=5f2b...
{ "id": "7d0e2a41-9b3c-4f6e-8a1d-52c4e9b07f13",
"event": "message.sent",
"created_at": "2026-09-15T08:00:00.000Z",
"data": { "id": "0f9c7a55-3d84-4b1e-9a60-27ce1f0b4d93" } }The body is always id, event, created_at and data. id names the delivery: it is present on every delivery made by the queue and the same on each automatic retry of it, so a receiver that already handled it can recognise a retry. A redelivery you ask for (the endpoint above, or the Webhooks screen's button) is a new delivery with a new id carrying the same event and data — to treat it as a repeat, compare event and data rather than id. created_at is stamped per attempt. For message.sent and message.failed, data is { "id": "<message id>" }; for channel.status_changed it is { "id": "<channel id>", "status": "..." }.
message.received carries the message itself rather than only its id — { "id": "...", "channel_id": "...", "from": "+15551234567", "type": "text", "text": { "body": "..." }, "sent_at": "..." }. For anything but text, type is image, video, audio, document, sticker, location or contact, and one more field is named after it: a file carries media_id, mime_type, size, an optional caption and filename, and url — /v1/media/:id below. A voice note also carries transcript when this deployment transcribes them. text.body is always there, as the caption or a label such as Photo
, so a receiver written for text keeps working. The others answer something you just asked for and already hold the id of; nobody asked for this one, so a receiver holding only an id would have to call back before it could decide whether the message was interesting. sent_at is WhatsApp's own timestamp, which is how you tell a message that just arrived from one replayed after an outage.
poll.vote fires when somebody votes on a poll you sent, or changes their vote: { "id": "<poll message id>", "channel_id", "voter": "+1555…", "options": ["Tue"], "poll": { "question", "options", "results": { "Mon": 3, "Tue": 5 }, "voters": 8 } }. options is the voter's current choice, empty when they took it back; results counts each person once. The poll's message on /v1/messages carries the same results. Official numbers do not send polls.
status.posted fires when a contact posts to their WhatsApp status: { "channel_id", "from", "type": "text" | "image" | "video" | "audio", "text", "posted_at" }. It was said to nobody, so it never reaches the Inbox and this is the only place it appears. A poll somebody sends you arrives as message.received with type poll. A tap on buttons or a list row you sent, a template's quick-reply button, or a filled-in Flow arrives as message.received with type reply: { "to": "button" | "list" | "flow", "id", "title", "answers" } — the id you gave the button or row, and a Flow's answers field by field with message_id, the Flow message they answer.
message.delivered and message.read are what WhatsApp told us AFTER the send, and both carry { "id": "<message id>" }. They move the message’s status too, so a client that polls sees the same fact. Two things are worth knowing before you build on them.
They only ever move forwards. A reconnecting session replays the receipts it missed, and a receipt that would take a message backwards is discarded rather than announced — so you will not be told twice that one message was read, and a delivered arriving after a read is ignored.
And message.read depends on the recipient. Anyone can turn read receipts off on their own phone, and when they have, the message stops at delivered and stays there however many times they read it. Silence is not evidence the message went unread, and a workflow that waits for message.read will wait forever for those people. delivered has no such switch.
Answer 2xx and we consider it delivered. A 5xx, a timeout (we wait 10 seconds) or a refused connection is retried with backoff. A 4xx is not retried — you rejected it, and retrying will not change that, with two exceptions: 429 and 408 are asking us to come back, so we do. A 3xx is not followed at all: a redirect could bounce a signed payload to a host you never registered. Delivery is at-least-once, so make your handler idempotent.
Starting a conversation, and the limit on it
Your account may message a limited number of people a day who have never written to you. Replying to somebody who wrote first does not count and is never refused, however many replies you send — the limit is on starting conversations, not on having them.
Past it, a send answers 429 with code rate_limited, scope set to new_conversations_per_day, and retry_after_seconds counting to the next UTC midnight. Treat it as backpressure and wait out the window — not as an outage, and not as a reason to retry every second. Your current limit is shown on your panel's front page.
Why this exists. WhatsApp takes numbers away for unsolicited messages, and it does so on behaviour rather than on volume: a support desk answering four hundred people is unremarkable, and four hundred first-contacts with strangers is not. The numbers here share an address, so one account's cold outreach costs other people their numbers. This is the bound that stops that.
A separate 429 with scope set to messages_per_minute is an ordinary burst limit — retry shortly; it carries retryable: true, as does new_contacts_hourly. And a 403 reading Sending is paused on this account
is a decision somebody made, not a limit that resets; your inbox keeps working while it stands.
When WhatsApp restricts the number itself. WhatsApp can stop a number starting new conversations for a while — its reach-out time-lock, error 463 — while keeping existing ones open. We learn it from WhatsApp directly where the session reports it, and otherwise from three refusals inside an hour. From then until it lifts, a send to somebody who has never written to that number answers 429 with scope set to channel_restricted, restricted_until and retry_after_seconds; replies are untouched. The channel carries the same end time as restricted_until. Do not route around it with another number: every attempt during a restriction counts against the number, and a restriction ignored is how a number ends up banned.
A number paired recently is held to less. For its first week a number may start five new conversations on its first day, growing by 1.8 a day — 5, 9, 16, 29, 52 — before only your account’s own allowance applies. Past it a first contact answers 429 with scope set to number_warming_up, limit and retry_after_seconds to the next UTC midnight. The age is the number’s, not the channel’s: a new SIM paired into an old channel is new to WhatsApp. Replies are never counted, at any age.
If a firewall sits in front of your endpoint
Every delivery is sent with User-Agent: Sendbu-Webhooks/1.0 (+https://sendbu.com/docs). That is the string to allow if a WAF or bot filter is in front of your handler — Cloudflare, AWS WAF and Vercel's firewall all challenge or block unattended POSTs by default.
The symptom is a silence with nothing in your logs. An edge block happens before your application is reached, so your access log is empty while ours records a 403 and gives up — a 4xx is not retried. If your webhook page shows repeated 403s that your own server never saw, this is why: allow the agent above, or allow our egress address, and then look for the retry.
A 429 is different and you do not need to work around it. If your endpoint rate-limits us, say so with a 429 and we back off and try again rather than dropping the event.
Verifying the signature
Every delivery carries a Sendbu-Signature header: t=<unix seconds>,v1=<hex>. The v1 value is HMAC-SHA256 over the exact string `${t}.${rawBody}`, keyed with your endpoint's secret.
Reject anything whose t is more than 300 seconds away from your clock in either direction — that is the replay window we verify against — and compare the digests in constant time.
import { createHmac, timingSafeEqual } from 'node:crypto'
// `body` must be the RAW request body, byte for byte. Parsing it to JSON and
// re-serialising changes the bytes and every signature then fails.
function verify(secret, body, header) {
const parts = new Map(header.split(',').map((p) => p.split('=')))
const t = Number(parts.get('t'))
if (!Number.isFinite(t)) return false
if (Math.abs(Math.floor(Date.now() / 1000) - t) > 300) return false // replay window
const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest('hex')
const a = Buffer.from(parts.get('v1') ?? '', 'hex')
const b = Buffer.from(expected, 'hex')
return a.length === b.length && timingSafeEqual(a, b)
}Contacts
A contact is a phone number you know something about: a name, a few tags, and any fields of your own. It exists so that a message can be addressed to a person rather than a string — the fields become template variables, and the tags become the audience a campaign is drawn from.
On a WhatsApp Business number, a label your team puts on a chat on the phone becomes a tag on that person here — New customer
becomes wa_new_customer — and comes off when the label does, so a campaign can target what the team marks. It works one way: tags set here do not become labels on the phone.
Consent is a column, not a policy. opted_out_at is a timestamp, set when somebody asks not to be messaged, and it is deliberately not a tag — tags get imported over and forgotten. Nothing that sends in bulk includes an opted-out contact, and that filter lives in the query rather than in each caller. A campaign follow-up or an abandoned-cart reminder already waiting when somebody opts out is not sent either: it fails with opted_out. Replying to somebody who just messaged you, or a trigger confirming their order, is unaffected: answering a question is not marketing.
An inbound message whose whole text is stop, stopall, unsubscribe, quit, optout, opt out, abonelikten çık, abonelik iptal, aboneliği iptal et, mesaj istemiyorum, mesaj gönderme, listeden çıkar opts that number out, and creates the contact if we did not have one — a person messaged from a pasted list has no row, and refusing to record their wish because of that is how the same list reaches them again next month. The match is on the whole message, so please don’t stop sending these
is not one — but case, punctuation and emoji around the words, and Turkish letters typed with or without their marks, do not matter: Stop,
, STOP 🛑
, ABONELİK İPTAL
and abonelik iptal
all count. The Turkish ones are phrases on purpose: a single word such as iptal
or dur
is how people answer a bot’s question or an order update, so on its own it opts nobody out — nor do cancel
or end
, for the same reason. A keyword opts somebody out inside a menu flow too, unless it is exactly one of the options the menu is showing them.
Somebody who opted out that way can opt back in by sending start, başla, abone ol, matched the same way. An opt-out you set yourself, from the panel or the API, is not lifted by a message: clear it yourself. One the person made by keyword cannot be cleared through the API — opted_out: false answers 403 — only by them, or by an owner or admin in the panel.
GET/v1/contacts
Lists contacts, newest first. Filter with ?tag= (repeatable, matches any), ?opted_out=true|false and ?search=, which matches the number or the name.
Pages like messages: the response carries data, has_more and next_cursor, which you pass back as ?starting_after= (the older ?cursor= still works). limit is 1 to 200 and defaults to 50; a value outside that range, or an opted_out that is not true or false, answers 400 invalid_request naming the field. See paging — the reasoning is the same as for messages.
POST/v1/contacts
Takes phone_number (E.164), and optionally name, tags and attributes. Answers 201.
Tags and attribute names are lowercase letters, digits and underscores — the same rule as a template variable, so {{plan}} in a template and plan on a contact are visibly the same thing. Attribute values are strings: turning a number into text is a choice about wording, and it is yours rather than ours.
A number this organization already knows is refused rather than duplicated. Two rows for one phone is two opt-out states for one person, and only one of them would ever be checked.
GET/v1/contacts/:id
One contact. Another organization’s id answers exactly like one that never existed.
PATCH/v1/contacts/:id
Names only what changes. name, tags, attributes and opted_out; a field you do not mention is left alone, and "name": null clears it.
The number cannot be changed. It is the identity, so editing it in place would move every tag, attribute and opt-out onto somebody else’s phone. Getting one wrong is a delete and a create, which is loud.
DELETE/v1/contacts/:id
Answers 204, or 400 when the contact is opted out. That row is the only record of their refusal: delete it, re-import the same spreadsheet next month, and the campaign that goes out is the one they said no to. Clear the opt-out first if you really mean it.
GET/v1/contacts/:id/export
Everything this organization holds about the person, as one JSON document — the contact, every message either way, notes and satisfaction answers — for a data access or portability request.
POST/v1/contacts/:id/erase
Deletes all of it, files included, for an erasure request. Takes { "confirm": "erase" }, because it cannot be undone; answers what was deleted. The change log records who did it. Somebody who opted out keeps a do-not-contact record — their number and when they opted out, nothing else — so a later import cannot make them reachable again; opt_out_kept says when that happened.
Campaigns
One template, sent to everybody carrying a tag. A campaign names a channel, a template and some tags — and that is the whole of it. There is no free-text body and no pasted list of numbers, and both omissions are the feature.
A body written into the campaign could not be reviewed, reused or corrected afterwards; a template can be read before it goes and fixed for next time. A pasted list is a list with no opt-out state attached, which is precisely how somebody who unsubscribed last month receives this month’s send. Going through contacts means the consent check is not something the sender has to remember.
It is paced at one message per second. A channel here is a real WhatsApp account, and an account that emits hundreds of identical messages to strangers in a few seconds gets banned — on your number, the one your customers know. So the audience is spread out: a campaign to 500 people is accepted in a moment and lands over the following nine minutes.
The audience is resolved when it runs, not when it is written. A campaign scheduled for Friday reaches whoever is tagged on Friday, and does not reach somebody who opted out on Wednesday.
GET/v1/campaigns
Lists campaigns, newest first, as { "data": [...] }, with their counts and the first few per-recipient failures.
POST/v1/campaigns
Takes name, channel_id, template_key, tags and optionally send_at (ISO 8601 with an offset). Answers 202 — like POST /v1/messages, nothing has been sent yet.
Add up to five "follow_ups": [{ "after_hours": 48, "template_key": "nudge" }] and each person is also sent those templates that many hours after the first message — unless they answer first, which cancels the rest of theirs. They are scheduled messages, visible and cancellable like any other.
An empty tags means every reachable contact. It is allowed and it is not the default in any interface we build, because “everyone” is the audience somebody picks by accident.
Refused up front, while somebody can still fix it: an audience that reaches nobody, a channel that is disconnected or logged out, a send_at in the past — almost always a timezone got wrong, and sending immediately is the one outcome that cannot be undone — and one more than 90 days ahead.
Send an Idempotency-Key header to make a retry safe. Optional here; with one, a second create carrying the same key answers with the campaign the first one made — the same id, whatever the body says — and starts nothing new, just as on messages.
GET/v1/campaigns/:id
One campaign, with status, sent, failed and failures — the first 50 recipients it could not send to, each with the reason. The shape of that list is the diagnosis: the same reason repeated is a template problem, five different ones is a data problem.
status is scheduled, sending, sent, paused, cancelled or failed. sent means every recipient was attempted, not that every one succeeded — check failed. failed means the run broke, which is our fault rather than your data’s.
paused means the campaign stopped with people still to reach, and nothing of it goes out while it stays there — messages already waiting in the queue are withdrawn, with failure_code campaign_paused. Today that happens when the account is suspended; paused_at and paused_reason (account_suspended) say when and why, and are kept after a resume. Restoring the account does not resume it: resume or cancel it yourself. sent counts what actually left, so a campaign paused part-way shows how far it got. cancelled_reason is cancelled_by_user or cancelled_by_operator — we cancel a campaign ourselves only when suspending an account for spam or abuse.
You can poll this, or subscribe to campaign.finished and be told. That event carries the counts rather than an id, because they are the answer — fetching would be a second round trip for every campaign. campaign.paused, campaign.resumed and campaign.cancelled carry { "id", "name", "status", "reason" }.
POST/v1/campaigns/:id/cancel
Stops a scheduled or paused campaign for good and answers 204; the people it had not reached never get it, and its waiting messages are withdrawn (failure_code campaign_cancelled). A campaign that is sending answers 400 — its messages are already queued with their delays, and there is no cancel part-way through today.
POST/v1/campaigns/:id/resume
Takes a paused campaign up again and answers 202 with it. It reaches only the people it had not reached yet — anybody whose message already went is skipped, so nobody gets it twice. One that had not started waits for its send_at, or sends now if that time passed while it was paused; one that was part-way sends to the rest now, paced as before.
400 for any status but paused. While the account is suspended its keys do not authenticate at all, so a resume is only possible once it is restored.
Integrations
The other direction. Webhooks are us calling your system when something happens here; an integration is somebody else's system calling us to make a WhatsApp message go out. A shop marks an order fulfilled and the buyer gets a message with the tracking number, without you writing a line of code.
It is two objects. A template is the message, written once, with {{placeholders}} in it. A trigger is a URL you paste into the other platform, tied to one channel and one template. Shopify and WooCommerce are understood natively — their own signatures, their own payloads — and generic takes a body you compose yourself, which is how anything else reaches us: WordPress without a shop, Zapier, Make, n8n, a cron job, your own backend.
Templates
curl https://sendbu.com/v1/templates \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"key":"order_shipped",
"body":"Hi {{customer_name}}, order {{order_number}} is on its way. Tracking: {{tracking_number}}"}'A placeholder is lowercase letters, digits and underscores: {{order_number}}. Anything else — {{Name}}, {{order-number}} — is refused when you save it, rather than delivered to your customer verbatim. A value that is missing when the template fires is also a refusal, not an empty string: a message reading Hi , your order has shipped
has already reached somebody by the time you hear about it.
Unless you give it a fallback. {{customer_name|Değerli müşterimiz}} uses the text after the bar when the value is missing or blank, so the message reads Merhaba Değerli müşterimiz
instead of being refused. An empty fallback, {{tracking_url|}}, makes a value optional. The fallback is trimmed and cannot contain braces.
GET/v1/templates
Lists your templates, newest first, as { "data": [...] }. Each carries variables, derived from the body on every read.
POST/v1/templates
Takes key and body. Answers 201. Keys are unique per organization and are how a trigger refers to a template.
PATCH/v1/templates/:id
Takes body, and only body. A key cannot be renamed, because renaming one would silently break every trigger pointing at it.
DELETE/v1/templates/:id
Answers 204, or 400 while a trigger still sends this template. Delete the trigger first — we will not quietly take your live integrations with it.
Triggers
GET/v1/triggers
Lists your triggers with their url, and with last_fired_at, last_error and last_error_at — which is where to look first when a customer did not get a message.
POST/v1/triggers
Takes source (shopify, woocommerce, generic), channel_id, template_key, and event — the platform's own name for what happened, such as orders/fulfilled. An empty event means “fire on anything this URL receives”.
delay_minutes (0 to 10080) waits before sending. That is an abandoned-cart reminder on Shopify: event checkouts/create, a delay of about 60, and a template using {{checkout_url}}. Subscribe orders/create to the same URL as well: an order carrying that checkout's token cancels the reminder still waiting for it, and each checkout gets one reminder however often Shopify reports it changed. A cart trigger hears both checkouts/create and checkouts/update, so a checkout with no phone number yet is skipped until an update brings one — and it never answers an orders/… topic.
statuses (optional, up to 20) fires only when the order's status is one of them: WooCommerce's status (processing, completed…), Shopify's financial_status (paid…) or fulfillment_status (fulfilled…), compared without case. With a condition each order is messaged once per status, so subscribing orders/updated does not resend on every edit.
The template has to fit the source: a placeholder Shopify or WooCommerce never sends — {{tracking_number}} on WooCommerce, {{status}} on Shopify — is refused here, naming what the source does send, and so is a later edit of a template a trigger already uses.
secret is optional and the choice matters. On Shopify the shop generates the secret, so you paste theirs here. Otherwise leave it out and we generate a strong one, returned once in this response as secret — the same rule as an API key. A secret you supply is 16 to 200 characters; a shorter one is refused.
Answers 201 with the trigger wrapped, not bare: { "trigger": { "id", "url", … }, "secret": "whsec_…" }. The trigger object is the one GET /v1/triggers lists, and its url is where the platform posts. secret is present only when we generated it; a secret you supplied is not echoed back.
DELETE/v1/triggers/:id
Answers 204, and the URL stops working immediately. There is no rotate: the URL is not the credential, the secret is.
Auto-replies
Answering an inbound message without a person. Two kinds of rule: one fires when a message arrives while you are closed, the other when the message is one of a few words you have an answer ready for. Both send a template rather than free text, because an automatic message is the one nobody reads before it goes out — so it has to be readable somewhere before it is ever triggered.
A rule is per organization, not per channel. It answers on whichever of your numbers the message arrived at.
GET/v1/auto-replies
Lists your rules, oldest first, as { "data": [...] }. Each carries trigger, template_key, keywords, cooldown_minutes and enabled.
POST/v1/auto-replies
Takes trigger (outside_hours, keyword), template_key, keywords and cooldown_minutes. Answers 201.
keywords belongs to a keyword rule and is required there — a keyword rule with no keywords matches nothing, which is a rule that looks enabled and never fires. On an outside_hours rule keywords are refused rather than ignored: that rule fires on the clock and would never read them, and listing them back on a rule that does not use them is how you come to believe the matching is broken.
cooldown_minutes is how long before the same person can trigger the same rule again, and it is the field that matters most here. Without it, somebody messaging four times at midnight gets four identical “we are closed” replies — which from their side is not an auto-responder, it is a number that spams them back. It defaults to 240, four hours: long enough to cover an evening, short enough that tomorrow morning is a fresh conversation.
Matching is on the whole message, not as a substring, exactly like the opt-out keywords. What are your opening hours
contains hours and is a question a person should answer; hours on its own is somebody using the shortcut.
PATCH/v1/auto-replies/:id
Takes enabled, and only enabled. This is the endpoint for a bank holiday: turn the away message on this evening and off on Tuesday, keeping the wording and the cooldown a delete would throw away.
A rule's trigger, template and keywords cannot be edited. A cooldown that is already running does not record which version of the rule it was serving, so changing the wording underneath it would send the new text to somebody the old rule had already answered. Delete and create says that plainly; an edit would not.
DELETE/v1/auto-replies/:id
Answers 204. Any cooldown the rule was holding goes with it, so the next message gets answered by whatever rules remain.
GET/v1/auto-replies/hours
Answers { "configured": true, "hours": { "timezone": "...", "days": {...} } }.
configured is false when you have never saved any, and hours is then the default we would fire against — nine to five, Monday to Friday, UTC. It is there so you can tell a deliberate nine-to-five UTC from a tenant who has simply never set them, which matters the moment you create an outside_hours rule.
PUT/v1/auto-replies/hours
Takes timezone and days, and replaces both. PUT rather than PATCH because opening hours are one value: a day you leave out is a day you are closed, not a day left alone.
timezone is an IANA name — Europe/London, not +01:00. A fixed offset is wrong for half the year anywhere that changes its clocks, and wrong silently: the away message just starts an hour late every summer. A name this server does not recognise is refused here, rather than accepted and then quietly making every hours rule unevaluable.
Each day is either null for closed, or { "open": "09:00", "close": "17:00" } — 24-hour, minutes, no seconds. A close earlier than open means the day runs past midnight — { "open": "18:00", "close": "02:00" } is one evening, and the small hours belong to the day that opened. What cannot be expressed is a lunch break: there is one range per day.
Shopify and WooCommerce
Create a trigger, then paste its url into the platform's own webhook settings and give it the same secret. We verify what they send the way they sign it — Shopify's X-Shopify-Hmac-Sha256, WooCommerce's X-WC-Webhook-Signature, both base64 HMAC-SHA256 over the raw body — and read the order fields out of their payload for you: {{order_number}}, {{customer_name}}, {{total}}, {{currency}}, {{tracking_number}} and a few more. The panel lists the exact set beside each source.
Phone numbers are sent in international format. We normalise what we reasonably can — separators, a 00 prefix, the (0) in +44 (0)20 …, a trunk zero after the country code as in +90 0532 …. A national number like 0532 123 45 67 is read against, in order: the country the order's own address names (WooCommerce's billing.country, Shopify's country_code, or a country field in a generic body), your organization's default country if you set one in Settings, and the country of the sending number. With none of those, or when it is not a valid number there, it is refused rather than guessed at: guessing does not fail loudly, it sends your customer's order confirmation to a stranger in another country. Contact imports use the default country the same way.
Anything else
POST/v1/hooks/:id
The trigger URL itself. No API key — it is authenticated by the signature, against that trigger's own secret.
For generic, you compose the body and sign it with the same scheme our outgoing webhooks use, in X-Sendbu-Signature. The verification example above is the same computation in the other direction, so one implementation covers both.
POST https://sendbu.com/v1/hooks/8f3c1d20-...
Content-Type: application/json
X-Sendbu-Signature: t=1757913600,v1=5f2b...
{ "event": "booking.confirmed",
"to": "+447700900123",
"values": { "name": "Ada", "when": "Tuesday at 15:00" } }Send an Idempotency-Key header if you can; without one we derive a key from the signature and the body, so a retry of the identical request still sends once. Shopify and WooCommerce both carry their own delivery id and are deduplicated by it.
200 with {"status":"sent","message_id":"…"} means a message is queued; message_id is the id GET /v1/messages/:id reads. (The same id also appears as messageId, the spelling this answered with first; it will be removed in a later release, so read message_id.) 200 with {"status":"ignored"} means we deliberately did nothing — the trigger is off, the event or status is not the one it watches, or it was WooCommerce's unsigned webhook_id=… ping — and it is a success on purpose, because shop platforms switch off a webhook that keeps failing. So is an order we could not use: no phone number, one without a country code, or a value the template needs and the order lacks. That answer carries a reason, and the same sentence is recorded as the trigger's last_error. A bad signature is 401, an unknown trigger 404, and a body that is not JSON 400; those are worth fixing at your end. A delivery whose signature does not verify is refused before anything else happens: it does not count towards the trigger's 200 deliveries a minute and is not recorded as its last_error, so somebody posting to the URL without the secret can neither crowd out the real platform nor make a working trigger look broken. Past the 200, a signed delivery answers 429 with Retry-After.
Errors
Every refusal has the same shape:
{
"error": {
"code": "channel_not_connected",
"message": "Channel 6b1f0c4e... is logged_out and cannot send. Connect it first.",
"retryable": false,
"channel_id": "6b1f0c4e-9a2d-4f77-bd31-0c5a7e2f9a10",
"status": "logged_out"
}
}code is the field to branch on — the message is written for a human and will be reworded. retryable says whether trying the identical request again could ever succeed. Some errors add fields beside those three, as channel_not_connected adds channel_id and status above; the three contract fields are never overwritten by them. Every 429 carries a Retry-After header in seconds, and retry_after_seconds in the body when the limit knows the figure — see rate limits.
| code | HTTP | What it means |
|---|---|---|
| invalid_request | 400 | The body, a field in it, or a required header is wrong. The message names what, and a field name is included where there is one. |
| unauthorized | 401 | No API key, or one that is wrong, revoked, or unknown. The repair is to check or rotate the key. |
| account_suspended | 403 | The key is fine and the account is stopped. Nothing to rotate — it starts working again the moment the account does. |
| forbidden | 403 | The credential is fine and this caller may not do this. Only a member with a higher role can, so rotating anything is the wrong move. |
| not_found | 404 | No such resource for this organization. Another tenant’s id answers exactly the same way as an id that never existed. |
| channel_not_connected | 409 | The channel is disconnected or logged out, so it cannot send. Connect it first; this never fixes itself. |
| capability_unsupported | 422 | The channel’s provider cannot do what the request asked of it. |
| rate_limited | 429 | Too many requests, or a sending limit was reached. Wait the seconds in the Retry-After header (also retry_after_seconds in the body), then retry. |
| quota_exceeded | 402 | This month’s message allowance for the plan is spent. Retrying will not help — it resets at the start of next month, or upgrade the plan. A retry carrying an idempotency key you have already used is never refused here, because it costs nothing new. |
| capacity_unavailable | 503 | We could not take the request right now. Retry. |
| internal_error | 500 | A bug on our side. The detail is in our logs, not in the response. |
From an AI assistant (MCP)
Sendbu is also a Model Context Protocol server, so an assistant such as Claude can use your numbers directly. Point the client at https://sendbu.com/mcp (Streamable HTTP) with the same key as /v1, sent as Authorization: Bearer sk_live_…. It offers five tools: list_channels, send_message, list_conversations, read_conversation and list_contacts.
send_message goes through exactly the path POST /v1/messages does, so every limit on this page applies — the daily first-contact limit, a young number's warm-up, a restriction WhatsApp has placed, the 24-hour window on official numbers. A refusal comes back to the assistant as a tool result with the reason and when to retry, rather than as an error it cannot read. A tool the key's scopes do not cover answers the same way, as forbidden with the required_scope.
Give send_message an idempotency_key. It is optional only so a one-off call from an assistant works; without one a random key is made for that call alone, so a retry after a timeout can send the message twice. With the same key, a retry returns the first message and sends nothing.
One JSON-RPC message per POST. A client that negotiated protocol 2025-06-18 — and says so in the MCP-Protocol-Version header, as that revision requires — has its batches refused with -32600, because that revision removed batching; under 2025-03-26 a batch of up to 20 is still answered. There is no event stream: GET, PUT, PATCH and DELETE on /mcp answer 405 with Allow: POST and the usual JSON error. Requests count against the same 300-a-minute budget as /v1.
With n8n, Make or Zapier
No plug-in is needed. Add a webhook endpoint here pointing at the automation's webhook trigger (n8n's Webhook node) and subscribe it to message.received — every message then starts a workflow, signed as described above. To answer, call POST /v1/messages from an HTTP Request node with Authorization: Bearer sk_live_… and an Idempotency-Key such as the received message's id, so a retried workflow sends once.
What is not built yet
Everything the home page admits, plus what only somebody writing code against this would ask. A reference that was less candid than the marketing page would be the more expensive lie; being more candid is the safe direction, which is why this list is the longer of the two.
- What waits on this deployment's own setup. Official numbers need its Meta app, and paying for a plan needs its Stripe account; the code for both is here and each switches on when its keys are set. Until then a channel is a phone of yours holding the session, and a plan is set by hand.
- A monthly allowance is enforced, and it is not billing. Past a plan’s allowance
POST /v1/messagesanswers402withquota_exceeded, which is not retryable — waiting until next month or changing plan is the only way through. It counts messages ACCEPTED, so one that later failed at WhatsApp still counted. The Usage screen in the panel shows where you stand.