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

# WhatsApp messages

> Send text and template messages, reply in a conversation, and poll message status and inbound replies.

Send WhatsApp messages and read their status. The backend resolves the sender, the recipient, and the 24-hour window for you, so payloads carry content only. Full reference and live try-it: [Karibu WhatsApp API](/Karibu-WhatsApp/index).

<Note>
  One endpoint (`POST /messages`), one body shape discriminated by `type` (`text` / `template` / `media` / `interactive`). Target it with `to` (first contact) or `conversation_id` (reply). Sends are async: you get **202** with `{ message_id, status: "pending" }`, then poll `GET /messages/{message_id}` or receive a webhook.
</Note>

<Warning>
  Templates always go and reopen the 24h window. `text` / `media` / `interactive` need an **open** window and return **422 `WINDOW_CLOSED`** otherwise. For first contact, send a template.
</Warning>

## Send to a number (first contact)

Provide `to`. `sender_id` is optional, the backend resolves it.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://karibu.briq.tz/v1/whatsapp/messages" \
    -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
    -d '{ "to": "255712345678", "type": "template", "template_name": "welcome", "variables": { "1": "Asha" } }'
  ```

  ```python Python theme={null}
  import requests
  r = requests.post(
      "https://karibu.briq.tz/v1/whatsapp/messages",
      headers={"X-API-Key": "YOUR_API_KEY"},
      json={"to": "255712345678", "type": "template", "template_name": "welcome", "variables": {"1": "Asha"}},
  )
  print(r.json())
  ```

  ```javascript Node.js theme={null}
  const r = await fetch("https://karibu.briq.tz/v1/whatsapp/messages", {
    method: "POST",
    headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
    body: JSON.stringify({ to: "255712345678", type: "template", template_name: "welcome", variables: { "1": "Asha" } }),
  });
  console.log(await r.json());
  ```
</CodeGroup>

## Reply in a conversation

Same endpoint, but provide `conversation_id` instead of `to`. Sender and recipient come from the thread, so you send content only (no `to`, no `sender_id`).

```bash theme={null}
curl -X POST "https://karibu.briq.tz/v1/whatsapp/messages" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "conversation_id": "CONVERSATION_ID", "type": "text", "body": "Thanks, your order ships today." }'
```

Template reply (reopens the window):

```bash theme={null}
curl -X POST "https://karibu.briq.tz/v1/whatsapp/messages" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "conversation_id": "CONVERSATION_ID", "type": "template", "template_name": "order_update", "variables": { "1": "A1234" } }'
```

<Note>
  Provide exactly one of `to` (first contact) or `conversation_id` (reply). Sending both, or neither, is `422 VALIDATION_ERROR`.
</Note>

## Check status

`message_id` is the id returned at send time. Status walks `pending -> sent -> delivered -> read`, or `failed`. For outbound messages, a paired inbound `reply` is included once it arrives.

```bash theme={null}
curl "https://karibu.briq.tz/v1/whatsapp/messages/MESSAGE_ID" -H "X-API-Key: YOUR_API_KEY"
# -> { "data": { "status": "delivered", "provider_message_id": "wamid....", "reply": null } }
```

## Poll messages and responses

List newest-first across the workspace, or scope to one thread. Filter to inbound to read responses without webhooks.

```bash theme={null}
curl "https://karibu.briq.tz/v1/whatsapp/messages?conversation_id=CONVERSATION_ID&direction=inbound&since=2026-06-24T00:00:00Z" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Read receipt

Mark an inbound message read on WhatsApp (the blue ticks), by its internal `message_id` (the `id` from `GET /messages`). The provider id is resolved for you.

```bash theme={null}
curl -X POST "https://karibu.briq.tz/v1/whatsapp/messages/MESSAGE_ID/read" -H "X-API-Key: YOUR_API_KEY"
```