This guide takes you from an empty workspace to a message on a phone: a token, some balance, one request, and the statuses the message moves through afterwards. Every request goes to https://api.bweze.com, and every path starts with /v1.
Get a token that can send
In BWEZE Platform, open Manage workspace › API tokens and create a token from the Send SMS template. It grants message:read and message:send and nothing else. message:send sends; message:read previews.
- Copy the secret when it is shown. It starts with
bw_sk_. BWEZE shows it once and keeps only a hash. - Keep it on your server. Publishable tokens (
bw_pk_...) can only read, so they cannot send. - Make one token per job. The server that sends SMS gets its own, so you can narrow, roll or revoke it without touching anything else.
To see what a token can do, call GET /v1/me. It returns the token’s workspace, owner, permissions, resources and expiry:
curl https://api.bweze.com/v1/me -H "authorization: Bearer bw_sk_..."
Add some balance
Sends are prepaid from the workspace wallet at 15 RWF per segment. A workspace owner tops up under Billing in BWEZE Platform, by mobile money or card. On Hobby and Pro, sends spend the month’s usage credit first. A send the available balance cannot cover is refused with 402 insufficient_balance, and nothing is charged.
Send the message
curl -X POST https://api.bweze.com/v1/messages \
-H "authorization: Bearer bw_sk_..." \
-H "content-type: application/json" \
-d '{
"to": "+250788123456",
"template": "Your code is {{code}}",
"data": { "code": 4821 },
"idempotencyKey": "signup-4821"
}'
tois a phone number in international format. A number that starts with0is read as Rwandan, so0788123456is+250788123456.- The text is either
body, a literal string, ortemplatewithdatato fill it. idempotencyKeymakes the send safe to retry. You can send it as anIdempotency-Keyheader instead. Retrying an SMS send without sending it twice explains how to choose one.
Read the response
{ "id": "...", "status": "sent", "segments": 1, "encoding": "GSM7", "providerMessageId": "..." }
The HTTP status tells you where the message is:
| HTTP | status |
What it means |
|---|---|---|
200 |
sent |
The SMS gateway took the message |
202 |
queued |
The gateway is not connected, and the message waits |
segments is the number you are billed for, and encoding is the alphabet the message went out in. A send that fails answers with an error and a code instead; SMS API errors lists each one and what to do about it.
Follow it to delivered
After the send, delivery receipts move the message forward, never back:
| Status | Meaning |
|---|---|
queued |
Accepted, not yet handed to a carrier |
sent |
Handed to a carrier |
delivered |
The phone received it |
failed, rejected, expired |
It will not arrive |
unknown |
The carrier gave no final answer |
You see each message’s status in BWEZE Platform. There is no API endpoint or webhook for delivery status yet, so your code knows what the send response told it and nothing after that.
Preview before you send
POST /v1/messages/preview takes the same body as a send. It sends nothing and charges nothing, and it needs message:read:
curl -X POST https://api.bweze.com/v1/messages/preview \
-H "authorization: Bearer bw_sk_..." \
-H "content-type: application/json" \
-d '{ "to": "+250788123456", "template": "Your code is {{code}}", "data": { "code": 4821 } }'
It returns { encoding, segments, length }. Call it to show the cost before a send, or in your tests, so a template change that adds a segment fails the build. A message can be at most 10 segments; a longer one is refused with 400 message_too_long. GSM-7 or Unicode explains why one character can double a message’s segments.
From the CLI or the SDK
The CLI, @bweze/cli, needs Node.js 18 or later. bweze sms takes its token from BWEZE_API_KEY and ignores the saved login:
npm i -g @bweze/cli
export BWEZE_API_KEY=bw_sk_...
bweze sms preview --body "Your code is 4821"
bweze sms send --to +250788123456 --body "Your code is 4821" --confirm
Without --confirm, send only previews.
In Node, @bweze/messaging makes the same call:
import { BwezeMessaging } from '@bweze/messaging';
const sms = new BwezeMessaging({ apiKey: process.env.BWEZE_API_KEY! });
const result = await sms.send({
to: '+250788123456',
template: 'Your code is {{code}}',
data: { code: 4821 },
idempotencyKey: 'signup-4821',
});
result.status and result.segments are the fields from the response above. An error throws a typed BwezeError with the same code and docs URL as the HTTP API.
The full reference
The messaging docs cover sending, previews, segments, opt-outs and failure modes. The quickstart builds a small Node service on this call that texts a sign-in code and checks it. The current price of a segment is on the pricing page.