> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS

> Send transactional and bulk SMS on Safaricom, Airtel and Telkom, and track every delivery.

There are two ways to send:

> [card] Direct send
>
> One call, sent straight away to up to 1,000 numbers. Use it for OTP codes, order updates, alerts and reminders.
>
> [`POST /sms/send`](https://docs.telaven.com/api-reference/sms/send-sms)

> [card] [Campaigns](https://docs.telaven.com/guides/sms-campaigns.md)
>
> Send to contact lists and tags, personalised with each person's name, now or on a schedule.
>
> [SMS campaigns guide →](https://docs.telaven.com/guides/sms-campaigns.md)

## Send a message

```bash theme={null}
curl -X POST https://app.telaven.com/api/v1/sms/send \
  -H "Authorization: Bearer $TELAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["0712345678", "+254733000111"],
    "message": "Your order #1042 is on the way."
  }'
```

**to** `string | string[]` *required*

One number, or up to 1,000, in local or international format.

**message** `string` *required*

Up to 1,600 characters. Messages over 160 GSM or 70 Unicode characters are sent in parts.

Each accepted message is charged at your current price. Numbers that replied STOP to you are skipped.

## Delivery status

A recipient's `status` moves from `queued` to `sent` (the network accepted it) to `delivered` or `failed`.

* **Push:** subscribe to the `sms.delivered` and `sms.failed` [webhooks](https://docs.telaven.com/guides/webhooks.md).
* **Pull:** call [`GET /sms/messages/{id}`](https://docs.telaven.com/api-reference/sms/get-message), or list them with [`GET /sms/messages?status=failed`](https://docs.telaven.com/api-reference/sms/list-messages).

> [!TIP]
>
> Messages reported as failed are **refunded to your wallet automatically**.

## Sender ID

Messages go out under your approved sender ID, so recipients see your brand name. Apply for one in the dashboard under **Send SMS → Sender ID**.

## Opt-outs

Every outgoing SMS ends with the opt-out instruction the regulator requires (`STOP to *456*9*5#`). Anyone who replies STOP is left out of your future sends automatically, and you receive an `sms.opt_out` webhook.

## Replies

Replies to your shortcode or number arrive as `sms.inbound` webhooks:

```json theme={null}
{ "from": "+254712345678", "to": "22384", "text": "What time do you open on Saturday?" }
```

## Analytics

* [`GET /sms/analytics`](https://docs.telaven.com/api-reference/sms/sms-analytics) gives totals, delivery rate, cost and per-campaign results for a period (`days`, or `from`/`to`).
* [`GET /sms/analytics/daily`](https://docs.telaven.com/api-reference/sms/daily-sms-analytics) gives sent, delivered and failed counts per day.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.