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

# WhatsApp

> Send approved WhatsApp templates (order updates, reminders, codes, offers) and get replies and read receipts on your webhook.

Messaly is built on Meta's official WhatsApp Cloud API.

## Which number sends

[`GET /whatsapp/numbers`](https://docs.telaven.com/api-reference/whatsapp/get-sending-number) tells you which number your messages go out from, and your price per template category:

* **`own`**: your business number, connected in the dashboard under **WhatsApp → Settings**.
* **`shared`**: the Messaly shared number, used when you haven't connected one (if it's available to you). On the shared number you can only send templates you created there, and new templates are reviewed by Messaly before they go to Meta.

```json theme={null}
{
  "data": [{ "kind": "own", "phone": "+254 712 345678", "status": "ready" }],
  "sharedAvailable": true,
  "pricesCents": { "marketing": 150, "utility": 80, "authentication": 80 }
}
```

## Before you start

**1. Connect a number**

Connect your WhatsApp Business number under **WhatsApp → Settings**, or use the shared number.

**2. Get a template approved**

Create one with [`POST /whatsapp/templates`](https://docs.telaven.com/api-reference/whatsapp/create-whatsapp-template) or in the dashboard. Only `approved` templates can be sent. Approval usually takes minutes.

**3. Create an API key with the whatsapp:send scope**

Under **Settings → API keys**.

**4. Top up your wallet**

Each template message is charged when it's sent, at its category's price.

## Send a template

```bash theme={null}
curl -X POST https://app.telaven.com/api/v1/whatsapp/send \
  -H "Authorization: Bearer $TELAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0712345678",
    "name": "Jane Wanjiku",
    "template": {
      "name": "order_ready",
      "language": "en",
      "params": {
        "body": ["Jane", "A1042"],
        "header": { "media": { "type": "image", "link": "https://example.com/order.jpg" } },
        "buttons": [{ "index": 0, "text": "A1042" }]
      }
    }
  }'
```

```json theme={null}
{
  "success": true,
  "id": "4b7e…",
  "wamid": "wamid.HBgMMjU0NzEyMzQ1Njc4FQIAERgS…",
  "status": "sent",
  "number": "own",
  "costCents": 80
}
```

Keep the `wamid`: delivery and read receipts refer to it.

> [!NOTE]
>
> **The API only sends templates.** WhatsApp lets a business start a conversation only with an approved template. Within 24 hours of a customer's last message you can reply freely from the WhatsApp inbox in the dashboard.

## Campaigns

Send one template to many people, personalised for each:

1. **Estimate it.** [`POST /whatsapp/campaigns/estimate`](https://docs.telaven.com/api-reference/whatsapp/estimate-whatsapp-campaign) returns the number of recipients, opt-outs, the total cost and whether your wallet covers it. It sends nothing.
2. **Create it.** [`POST /whatsapp/campaigns`](https://docs.telaven.com/api-reference/whatsapp/create-whatsapp-campaign) takes contact lists, tags, or your own upload of up to 10,000 recipients, plus a `variableMap` that says where each template variable's value comes from. Add `scheduledAt` to send later.
3. **Follow it.** [`GET /whatsapp/campaigns/{id}`](https://docs.telaven.com/api-reference/whatsapp/get-whatsapp-campaign) gives counts by status, the amount spent and the latest failures.

If the wallet runs out partway through, the campaign stops with status `failed`. Top up, then resume it with [`PATCH /whatsapp/campaigns/{id}`](https://docs.telaven.com/api-reference/whatsapp/resume-or-cancel-whatsapp-campaign) `{"action":"resume"}`. Nobody is messaged or charged twice.

## Replies and receipts

Subscribe a [webhook](https://docs.telaven.com/guides/webhooks.md) to:

| Event | When |
| - | - |
| `whatsapp.inbound` | A customer messages your WhatsApp number. A customer who replies STOP arrives with `optOut: true`. |
| `whatsapp.status` | A message you sent is `sent`, `delivered`, `read` or `failed`. Match it to your send with `wamid`. |


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