# Messaging

Use Messaging to reach the people who matter to an organizer: everyone holding a ticket to an event, or the members of a fanbase. Pick email, SMS or WhatsApp, check who will get the message, then send it now or schedule it. Each send uses message credits that the organization tops up with M-Pesa or card through Payd.

## How the pieces fit

| Resource | What it is |
|---|---|
| Credits | The organization's balance for sending messages, in KES. Sends take credits and top-ups add them. |
| Audience | The attendees of one event, which you can narrow by ticket type, status, check-in and payment status. Or the active members of a fanbase. |
| Channel | `email`, `sms` or `whatsapp`. You choose one for each send. |
| Communication | One send. It has a `status`, a recipient count, delivered and failed counts and the credits it cost. |

A client uses them in this order:

1. Read the credit balance. Ask for an estimate for the channel and recipient count, and top up if the balance is short.
2. Count the recipients, and show the message as they will see it.
3. Send. The credits come off at once. Add `schedule_at` to send later.
4. Read the send's detail for delivered and failed counts. Credits for confirmed delivery failures go back to the balance.
5. To drop a scheduled event send, cancel it. The credits for the whole send go back.

Email needs a `subject`. An event SMS body must stay under 400 characters. WhatsApp messages go out as approved templates, and the render call shows the exact values. An event WhatsApp send returns `422` if WhatsApp is not set up for your tenant. A send with no matching recipients returns `422`, and one with too few credits returns `402` `insufficient_credits`.

Vabu also sends messages on its own when something happens, such as a ticket purchase or a fan reaching a new tier. You do not call an endpoint for those. Login codes belong to [Identity](https://docs.vabu.live/products/identity.md).

## What you can call today

### Credits

| Method | Path | What it does |
|---|---|---|
| GET | `/v1/organizer/credits/balance` | Get the credit balance and the low-balance level. |
| POST | `/v1/organizer/credits/estimate` | Get the cost of a send for a channel and recipient count. |
| POST | `/v1/organizer/credits/top-up` | Start a Payd checkout to add credits. Returns a `checkout_url`. |
| GET | `/v1/organizer/credits/transactions` | List top-ups, sends and refunds. |

### Check before you send

| Method | Path | What it does |
|---|---|---|
| GET | `/v1/organizer/events/{event}/communications/preview` | Count the attendees a send would reach. |
| GET | `/v1/organizer/fanbase/communications/preview` | Count the members a send would reach for a channel. |
| POST | `/v1/organizer/communications/preview-render` | Show a message as email, SMS or WhatsApp recipients will see it. |

### Event attendees

| Method | Path | What it does |
|---|---|---|
| POST | `/v1/organizer/events/{event}/communications/{channel}` | Send to attendees. `channel` is `email`, `sms` or `whatsapp`. |
| GET | `/v1/organizer/events/{event}/communications` | List an event's sends. Filter by channel and status. |
| GET | `/v1/organizer/events/{event}/communications/{id}` | Get one send with its recipients and delivery results. |
| DELETE | `/v1/organizer/events/{event}/communications/{id}` | Cancel a queued or scheduled send and get the credits back. |

### Fanbase members

| Method | Path | What it does |
|---|---|---|
| POST | `/v1/organizer/fanbase/communications/email` | Send an email to active members. |
| POST | `/v1/organizer/fanbase/communications/sms` | Send an SMS to members with a phone number. |
| POST | `/v1/organizer/fanbase/communications/whatsapp` | Send a WhatsApp message to members with a phone number. |
| GET | `/v1/organizer/fanbase/communications` | List sends, with a count for each channel. |
| GET | `/v1/organizer/fanbase/communications/{id}` | Get one send with its recipients and credit cost. |

### Your own alerts

| Method | Path | What it does |
|---|---|---|
| PUT | `/v1/organizer/settings/notifications` | Choose which alerts the organizer gets, such as ticket purchases and payouts. |

Full parameters and responses are in the [API reference](https://docs.vabu.live/api.md).

Here is an SMS to every attendee, scheduled for the afternoon before the show:

```sh
curl -X POST https://api.vabu.live/v1/organizer/events/$EVENT_ID/communications/sms \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "X-Tenant-Code: $TENANT_CODE" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Doors open at 7pm. Bring your ticket.",
    "recipients": { "type": "all" },
    "schedule_at": "2026-11-20T15:00:00+03:00"
  }'
```

The response gives the send an `id`, its `status`, `recipients_count`, the credits taken and your new balance.

## Calling these endpoints

Every route here takes a signed-in user token (`Authorization: Bearer ...`, a Vabu ID or Payd ID token) plus `X-Tenant-Code`, in live mode. They also accept an optional `X-Organization-Id` header to pick which organization you act for. Test keys and publishable keys are refused on these routes today. See [which credentials each endpoint takes](https://docs.vabu.live/concepts/keys-and-scopes.md#which-credentials-each-endpoint-takes).

Any active member can read balances and fanbase sends. Fanbase sends need the Owner, Admin or Editor role, and top-ups and alert settings need Owner or Admin. Event calls follow the event manager's role. For paging and error shapes, see [pagination](https://docs.vabu.live/concepts/pagination.md) and [errors](https://docs.vabu.live/concepts/errors.md).

## Related

- [Fanbases](https://docs.vabu.live/products/fanbases.md) for the members you message.
- [Events](https://docs.vabu.live/products/events.md) for the attendees you message.
- [Payments](https://docs.vabu.live/products/payments.md) for how top-ups are paid.
- [Identity](https://docs.vabu.live/products/identity.md) for login codes by WhatsApp or SMS.