# List conversations

> List inbox threads, most recently active first. Filter by from (one of your addresses) and channel. Each conversation carries from, the address it was last handled from.

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

List inbox threads, most recently active first. Filter by `from` (one of your addresses) and `channel`. Each conversation carries `from`, the address it was last handled from.

## Parameters

- `channel` (query, string): Only threads that have carried this transport. One of: `sms`, `sms_oneway`, `whatsapp`, `telegram`, `email`, `instagram`, `messenger`, `voice`.
- `from` (query, string): Keep only threads last handled from this address. Resolved like `from` on `POST /v2/messages`, narrowed by `channel` when given.
- `search` (query, string): Identity search (number, email, username). Never message bodies.
- `limit` (query, integer)
- `cursor` (query, string): Opaque `nextCursor` from the previous page.

## Responses

### 200

Threads, most recently active first (by relevance when `search` is set).

- `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): A transport a message travels on. One of: `sms`, `sms_oneway`, `whatsapp`, `telegram`, `email`, `instagram`, `messenger`, `voice`.
    - `direction` (string, required) One of: `inbound`, `outbound`.
    - `at` (string<date-time>, required)
  - `messageCount` (integer, required)
  - `unreadCount` (integer, required): Inbound messages not yet marked read. Reset with POST /v2/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)
  - `from` (string, nullable): The address this thread was last handled from, on the transport of its last message. Pass the conversation's `id` as `conversationId` on `POST /v2/messages` to reply from it. A thread opened by an API send before /v2 recorded no sender; its `from` is read off its messages. `?from=` on the list matches threads by the recorded sender only, which messages sent through /v2 record.
- `nextCursor` (string, nullable)

### 400

Invalid query.

- `code` (string, required)
- `message` (string, required)
- `details` (object): Machine-readable context. Keys that mean the same thing everywhere: - `errors`: present on every `400 invalid_request` for an invalid body or query parameter, `[{path, message, ...}]`, `path` naming the field (`["to"]`, `["contacts", 2, "recipient"]`, `["limit"]`). - `recommendation`: one sentence saying what to do next. - `dashboardUrl`: the dashboard screen that fixes it. - `connect`: on `409 no_channel`, the channels this project can connect to reach the recipient, each `{type, request, note, available, dashboardUrl?}`; `request` is the exact call (`POST /v2/channels` with its body, or `POST /v2/numbers`), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). `available: false` says why in `note` (one-way SMS closed until business verification is approved). - `address` / `from`: the address the error is about, under the name the request used for it.
  - `errors` (object[])
    - `path` (object[], required)
    - `message` (string, required)
    - `code` (string)

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object): Machine-readable context. Keys that mean the same thing everywhere: - `errors`: present on every `400 invalid_request` for an invalid body or query parameter, `[{path, message, ...}]`, `path` naming the field (`["to"]`, `["contacts", 2, "recipient"]`, `["limit"]`). - `recommendation`: one sentence saying what to do next. - `dashboardUrl`: the dashboard screen that fixes it. - `connect`: on `409 no_channel`, the channels this project can connect to reach the recipient, each `{type, request, note, available, dashboardUrl?}`; `request` is the exact call (`POST /v2/channels` with its body, or `POST /v2/numbers`), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). `available: false` says why in `note` (one-way SMS closed until business verification is approved). - `address` / `from`: the address the error is about, under the name the request used for it.
  - `errors` (object[])
    - `path` (object[], required)
    - `message` (string, required)
    - `code` (string)

### 404

`from` names no address of this project.

- `code` (string, required)
- `message` (string, required)
- `details` (object): Machine-readable context. Keys that mean the same thing everywhere: - `errors`: present on every `400 invalid_request` for an invalid body or query parameter, `[{path, message, ...}]`, `path` naming the field (`["to"]`, `["contacts", 2, "recipient"]`, `["limit"]`). - `recommendation`: one sentence saying what to do next. - `dashboardUrl`: the dashboard screen that fixes it. - `connect`: on `409 no_channel`, the channels this project can connect to reach the recipient, each `{type, request, note, available, dashboardUrl?}`; `request` is the exact call (`POST /v2/channels` with its body, or `POST /v2/numbers`), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). `available: false` says why in `note` (one-way SMS closed until business verification is approved). - `address` / `from`: the address the error is about, under the name the request used for it.
  - `errors` (object[])
    - `path` (object[], required)
    - `message` (string, required)
    - `code` (string)

## Example

```bash
curl -X GET "https://api.zavu.dev/v2/conversations" \
  -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.v2.conversations.list();

console.log(result);
```