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

# Conversations

> List, get, and update WhatsApp conversations with the TypeScript SDK

Kapso exposes conversation history via the Meta proxy. Results include the phone number and the Kapso `phoneNumberId` that owns the conversation.

## List conversations

```ts theme={null}
import { buildKapsoFields } from '@kapso/whatsapp-cloud-api';

const page = await client.conversations.list({
  phoneNumberId: '123',
  status: 'active',
  lastActiveSince: '2025-01-01T00:00:00Z',
  limit: 20,
  fields: buildKapsoFields([
    'contact_name',
    'messages_count',
    'last_message_id',
    'last_message_type',
    'last_message_timestamp',
    'last_message_text',
    'last_inbound_at',
    'last_outbound_at'
  ])
});

page.data.forEach((c) => {
  console.log(c.id, c.phoneNumber, c.status, c.phoneNumberId);
});
```

Common filters

* `status`: `active` | `ended`
* `lastActiveSince` / `lastActiveUntil`: ISO-8601 timestamps
* `phoneNumber`: filter by customer phone (E.164)
* `assignedUserId`: filter by active assignee user ID (must be a project member)
* `unassigned`: filter conversations with no active assignment (boolean, cannot be combined with `assignedUserId`)
* `fields`: specify Kapso extras (use `buildKapsoFields()` for the full set or `kapso()` to omit them). See [Kapso Extensions](/docs/whatsapp/typescript-sdk/kapso-extensions) for the conversation field list.

## Get a conversation

```ts theme={null}
const conv = await client.conversations.get({ conversationId: 'conv-123' });

// Example shape
// {
//   id: 'conv-123',
//   phoneNumber: '+15551234567',
//   status: 'active',
//   lastActiveAt: '2025-01-01T12:00:00Z',
//   phoneNumberId: '123',
//   metadata: {}
// }
```

## Update status

```ts theme={null}
await client.conversations.updateStatus({
  conversationId: 'conv-123',
  status: 'ended'
});
```

<Note>
  Conversations are available when using the Kapso proxy base URL. When calling Meta directly, this data is not provided by Graph.
</Note>