# 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.

Source: https://sms.bweze.com/guides/send-your-first-sms/ · Updated 2026-11-19

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](https://platform.bweze.com), 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:

```bash
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

```bash
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](/guides/retry-sms-safely/) explains how to choose one.

## Read the response

```json
{ "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](/guides/sms-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`:

```bash
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](/guides/gsm-7-vs-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:

```bash
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:

```ts

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](https://docs.bweze.com/docs/messaging) cover sending, previews, segments, opt-outs and failure modes. The [quickstart](https://docs.bweze.com/docs/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](/pricing/).

## Sources

- [BWEZE docs: Messaging](https://docs.bweze.com/docs/messaging)
- [BWEZE docs: API tokens](https://docs.bweze.com/docs/api-tokens)
- [BWEZE docs: API reference](https://docs.bweze.com/docs/api)
- [BWEZE docs: Billing](https://docs.bweze.com/docs/billing)
- [BWEZE docs: Quickstart](https://docs.bweze.com/docs/quickstart)
- [BWEZE docs: CLI](https://docs.bweze.com/docs/cli)
- [BWEZE docs: Building with agents](https://docs.bweze.com/docs/agents)
- [BWEZE price list (GET /v1/pricing)](https://api.bweze.com/v1/pricing)
