---
title: "List conversations"
locale: en
url: https://tlg.builera.app/en/docs/reference/rest/conversations.list
verified: 2026-10-24
app_version: "2.0"
generated: true
---

# List conversations

Chats newest first, filterable by account, status, unread, assignee, person or title. Titles and previews come from Telegram (untrusted).

Chats newest first, filterable by account, status, unread, assignee, person or title. Titles and previews come from Telegram (untrusted).

## Overview

| Name | Value |
| --- | --- |
| Code | `conversations.list` |
| Scope needed | `messages.read` |
| Risk | Read |
| May need confirmation | No |
| Runs as | Answers right away |
| Needs `Idempotency-Key` | No |
| Member roles allowed | `owner`, `manager`, `agent` |
| In the app | Inbox → chat list |

## Input fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accountId` | `uuid` | No |   |
| `status` | `"open" \| "waiting" \| "done"` | No |   |
| `unreadOnly` | `true/false` | No |   |
| `assigneeId` | `uuid` | No |   |
| `personId` | `uuid` | No |   |
| `folderId` | `uuid` | No |   |
| `q` | `text` | No |   |
| `limit` | `integer` | No |   |
| `cursor` | `text` | No |   |

## Example request

```bash
curl -X POST https://tlg.builera.app/api/public/v2/ops/conversations.list \
  -H "Authorization: Bearer $TELEGRAM_AUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Output fields (`data`)

| Field | Type | Required |
| --- | --- | --- |
| `items` | `object[]` | Yes |
| `next_cursor` | `null \| text` | Yes |

## Example answer

```json
{
  "data": {
    "items": [
      {
        "name": "text",
        "untrusted": true,
        "id": "00000000-0000-4000-8000-000000000000",
        "account_id": "00000000-0000-4000-8000-000000000000",
        "peer_kind": "text",
        "peer_tg_id": 1,
        "title": "text",
        "person_id": "00000000-0000-4000-8000-000000000000",
        "status": "open",
        "assignee_id": "00000000-0000-4000-8000-000000000000",
        "tags": [
          "text"
        ],
        "pinned": true,
        "unread_count": 1,
        "last_message_at": "2026-10-22T12:00:00.000Z",
        "last_message_text": "text",
        "last_message_out": true,
        "last_message_status": "failed",
        "last_inbound_at": "2026-10-22T12:00:00.000Z",
        "first_unanswered_at": "2026-10-22T12:00:00.000Z",
        "campaign_id": "00000000-0000-4000-8000-000000000000",
        "peer_status": "text",
        "peer_last_online_at": "2026-10-22T12:00:00.000Z",
        "members": "text",
        "created_at": "2026-10-22T12:00:00.000Z"
      }
    ],
    "next_cursor": "text"
  }
}
```

## Using it over MCP

Tool `conversations_list` is listed on the profiles: Real-time operations (`realtime`), Automation setup (`setup`), Discover (`prospecting`), Reports (`reports`), Administration (`admin`), Full (`full`). On other profiles, find it with `tools_search` and run it with `tools_run`.