Send your first SMS with the BWEZE API

Create a token that can send, top up the wallet, call POST /v1/messages, read the response, and follow the message to delivered.

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"
  }'
  • to is a phone number in international format. A number that starts with 0 is read as Rwandan, so 0788123456 is +250788123456.
  • The text is either body, a literal string, or template with data to fill it.
  • idempotencyKey makes the send safe to retry. You can send it as an Idempotency-Key header 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.

Sources

Copy linkMarkdown

/ More guides

Build the next thing, from Rwanda.

Get started