# List conversations

> Returns a paginated list of conversations grouped by contact phone number, sorted by most recent activity. Listing by inbox id or with pinned can return 400…

`GET /v2/api/conversations`

<Note>
**Required scope:** `CONVERSATIONS_READ`
</Note>

This endpoint is paginated. Use `page` and `size` query parameters to control results. See [Pagination](/docs/guides/pagination).

## Line or inbox

Send exactly one of `allo_number` or `inbox_id`. Sending both, or neither, returns `400` with code `INVALID_REQUEST`.

- `allo_number` lists the conversations of one Allo line. A line the caller cannot access returns `403` with code `ALLO_NUMBER_FORBIDDEN`.
- `inbox_id` lists the conversations of one of your [inboxes](/docs/inboxes/overview), with conversations from several lines (each row has one `allo_number`). The inbox's saved sources and filters apply, but not the app's Needs action and Mine tabs. "Unread only" is not saved on an inbox: pass the `unread` query parameter. An inbox that is not yours returns `404` with code `INBOX_NOT_FOUND`.

Each conversation has an `allo_number` field, the Allo line it is on. Use it to pin or reply when listing by inbox.

### Inbox and pinned errors

| Status | Code | When |
|--------|------|------|
| `400` | `INVALID_REQUEST` | Both `allo_number` and `inbox_id` are sent, or neither |
| `400` | `INVALID_PARAMETER` | A query parameter is malformed, for example `pinned=yes`. `param` names it |
| `400` | `FEATURE_NOT_SUPPORTED` | Listing by `inbox_id` or with `pinned` is not available yet. `param` names which one |
| `400` | `CONTACT_FILTER_NOT_SUPPORTED` | The inbox has saved contact filters and the workspace is still on the old contact model. Remove `contact_ids` and `contact_list_ids` from the inbox filters |
| `403` | `ALLO_NUMBER_FORBIDDEN` | The caller cannot access the `allo_number` line |
| `404` | `INBOX_NOT_FOUND` | No inbox with this ID for the caller. Right after a create it can be transient: when `retryable` is `true`, retry once |
| `422` | `CONTACT_FILTER_TOO_LARGE` | The inbox's contact filters resolve to too many numbers, or hold more than 50 contact IDs or 10 contact list IDs. The error `type` is `validation_error` |

## Pinned conversations

Each conversation has a `pinned` field. Pass `pinned=true` to list only pinned conversations, or `pinned=false` to leave them out. Pin and unpin with [Pin conversation](/docs/conversations/pin-conversation) and [Unpin conversation](/docs/conversations/unpin-conversation).

## Field notes

| Field | Null when |
|-------|-----------|
| `last_item.summary` | SMS items, or calls where AI summary is not yet available |
| `last_item.duration` | SMS items (only applies to calls) |
| `last_item.result` | SMS items (only applies to calls) |
| `last_item.recording_url` | Recording disabled, call not answered, or SMS items |
| `last_item.recording_duration` | Recording disabled, call not answered, or SMS items |
| `last_item.transcript` | Not requested via `extend=transcript`, or SMS items |
| `last_item.content` | Call items (only applies to SMS) |
| `last_item.status` | Call items (only applies to SMS) |
| `last_item.attachments` | Call items. An SMS with no photo or file returns an empty array. See [MMS attachments](/docs/conversations/get-item#mms-attachments). |
| `last_item.page_count` | Calls, messages that are not faxes, or a fax whose page count is not known yet |
| `last_item.contacts` | Empty array when no matching contact exists in the address book |

`last_item.duration` is the total call length in seconds, ringing included. `last_item.recording_duration` is the talk time, which is what the Allo app displays for recorded calls. For calls without a recording, the app falls back to `last_item.duration`.

### Extend parameter

The `extend` query parameter accepts a comma-separated list of optional fields to include. Currently supported:

| Value | Effect |
|-------|--------|
| `transcript` | Include full call transcripts on conversation items |

Passing an unsupported value returns a `400` error with code `UNSUPPORTED_EXTEND_VALUE`.
