# List conversations

> List inbox threads, most recently active first. A conversation groups every message with one contact across channels, which is what you need to build an inbox: GET /v1/messages returns a flat log with no thread to hang it on.

`GET https://api.zavu.dev/v1/conversations`

List inbox threads, most recently active first. A conversation groups every message with one contact across channels, which is what you need to build an inbox: `GET /v1/messages` returns a flat log with no thread to hang it on.

Use `senderId` to scope the list to a single number, and `channel` to keep only threads that have carried that channel.

## Parameters

- `channel` (query, string): Keep only threads that have carried this channel. One of: `sms`, `sms_oneway`, `whatsapp`, `email`, `telegram`, `instagram`, `messenger`, `voice`.
- `senderId` (query, string): Keep only threads last handled by this sender.
- `search` (query, string): Search threads by identity: phone number (any format — `+1 (555) 123-4567` and `15551234567` both match), email address (full or local part), WhatsApp username, or BSUID. Matching is by whole word, with prefix matching on the last term, so `mar` finds `maria@example.com` and `+1555` finds `+15551234567`; a fragment from the middle or end of a number (`4567`) does not match. It does **not** search message bodies — only who the thread is with. Results come back ranked by relevance rather than by recency, so the usual "most recently active first" ordering does not apply while `q` is set. `senderId` and `channel` still narrow the results, and `cursor` paginates them as usual. An empty or whitespace-only `q` returns no items rather than the full list.
- `limit` (query, integer)
- `cursor` (query, string): Opaque cursor from a previous response's `nextCursor`. Do not construct it.

## Responses

### 200

List of conversations.

- `items` (object[], required)
  - `id` (string, required)
  - `contactId` (string): ID of the contact this thread belongs to. Absent on group threads and on threads whose contact has not been resolved yet.
  - `contactIdentifier` (string, required): The key this thread is filed under: a phone number in E.164, a WhatsApp business-scoped user ID (BSUID), or a numeric chat ID (Telegram/Instagram/Messenger). It is not always a phone number, so do not parse it as one.
  - `email` (string): Email address of the thread, when the contact was reached by email.
  - `channels` (string[], required): Every channel this thread has carried messages on.
  - `lastMessage` (object, required): Denormalized preview of the most recent message, so a thread list needs no extra fetch.
    - `id` (string, required)
    - `text` (string, required): Text or caption. Empty when the last message carried no text (e.g. media).
    - `channel` (string, required): Delivery channel. Use 'auto' for intelligent routing. One of: `auto`, `sms`, `sms_oneway`, `whatsapp`, `telegram`, `email`, `instagram`, `messenger`, `voice`.
    - `direction` (string, required) One of: `inbound`, `outbound`.
    - `at` (string<date-time>, required)
  - `senderId` (string): Sender that last handled this thread. Use it as the `Zavu-Sender` header when replying so the answer leaves from the same number the contact knows.
  - `messageCount` (integer, required)
  - `unreadCount` (integer, required): Inbound messages not yet marked read. Reset with POST /v1/conversations/{conversationId}/read.
  - `whatsapp` (object): WhatsApp identity, present when the contact adopted a username.
    - `bsuid` (string): Business-scoped user ID. Can be used as `to` when sending.
    - `username` (string)
  - `createdAt` (string<date-time>, required)
  - `updatedAt` (string<date-time>, required)
- `nextCursor` (string, nullable)

### 400

Invalid query parameters.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

## Example

```bash
curl -X GET "https://api.zavu.dev/v1/conversations?search=%2B56912345678" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.conversations.list({
  search: "+56912345678",
});

console.log(result);
```