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

> List, search, find by recipient, read, mark read, and delete WhatsApp conversation threads.

A **conversation** is a thread between one of your WhatsApp senders and a customer number. All endpoints are scoped to the workspace behind your `X-API-Key`. Full reference and live try-it: [Karibu WhatsApp API](/Karibu-WhatsApp/index).

<Note>
  Phone numbers are E.164 digits, optional leading `+` (e.g. `255712345678`). Threads are addressed by their internal `conversation_id`.
</Note>

## List

Most recent first. Filter by `status` (`all`/`open`/`unread`), `sender`, `recipient`, or `search`.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://karibu.briq.tz/v1/whatsapp/conversations?status=unread&limit=20" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests
  r = requests.get(
      "https://karibu.briq.tz/v1/whatsapp/conversations",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={"status": "unread", "limit": 20},
  )
  print(r.json())
  ```

  ```javascript Node.js theme={null}
  const r = await fetch(
    "https://karibu.briq.tz/v1/whatsapp/conversations?status=unread&limit=20",
    { headers: { "X-API-Key": "YOUR_API_KEY" } },
  );
  console.log(await r.json());
  ```
</CodeGroup>

Each item carries `unread_count` and `window` (`{open, expires_at}`), so one call renders an inbox. Each item also echoes the sender: `sender_id` (internal UUID), `sender` (the sender's `phone_number_id`), and `sender_display_number` (the human number).

## Filter by sender

To see only the threads handled by one of your WhatsApp numbers, pass `sender`. It accepts any of three forms, so use whichever you have on hand:

| Value             | Example                           | Where to find it                                                  |
| ----------------- | --------------------------------- | ----------------------------------------------------------------- |
| WhatsApp number   | `+255712345678` or `255712345678` | the number you message from (spaces, dashes, and `+` are ignored) |
| `phone_number_id` | `1107264639145282`                | `sender` field on a conversation, or `GET /v1/whatsapp/senders`   |
| sender id (UUID)  | `949a36c7-...`                    | `sender_id` field, or `GET /v1/whatsapp/senders`                  |

```bash theme={null}
curl "https://karibu.briq.tz/v1/whatsapp/conversations?sender=255712345678" \
  -H "X-API-Key: YOUR_API_KEY"
```

If the value matches no sender in your workspace you get `404 SENDER_NOT_FOUND`; if a number matches more than one sender you get `409 SENDER_AMBIGUOUS`, in which case pass the `phone_number_id` or sender id instead.

<Note>
  `sender_id` (the UUID-only query param) still works but is deprecated. Prefer `sender`.
</Note>

## Summary

```bash theme={null}
curl "https://karibu.briq.tz/v1/whatsapp/conversations/summary" -H "X-API-Key: YOUR_API_KEY"
# -> { "total": 42, "open": 9, "unread": 5, "unassigned": 42 }
```

## Get one conversation

Fetch one thread by internal id.

```bash theme={null}
curl "https://karibu.briq.tz/v1/whatsapp/conversations/CONVERSATION_ID" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Find by recipient

Filter the list by the customer number. A number can match more than one thread (one per sender), so this returns a list; pass `sender` to narrow it.

```bash theme={null}
curl "https://karibu.briq.tz/v1/whatsapp/conversations?recipient=255712345678" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Read a thread's messages

Messages live on the messages collection. Scope to one thread with `conversation_id`, and filter with `direction`, `message_type`, `status`, `since`/`until`. See the [messages guide](/guides/whatsapp-messages).

```bash theme={null}
curl "https://karibu.briq.tz/v1/whatsapp/messages?conversation_id=CONVERSATION_ID&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Mark read

Clears inbox unread state (not a WhatsApp read receipt). `up_to` defaults to now.

```bash theme={null}
curl -X POST "https://karibu.briq.tz/v1/whatsapp/conversations/CONVERSATION_ID/read" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "up_to": "2026-06-24T09:12:00Z" }'
```

## Delete

Soft-delete, one-way; the thread leaves all lists.

```bash theme={null}
curl -X DELETE "https://karibu.briq.tz/v1/whatsapp/conversations/CONVERSATION_ID" \
  -H "X-API-Key: YOUR_API_KEY"
```