Как получить чаты и сообщения через API

Чаты и сообщения через API читаются двумя запросами: сначала список чатов бота, потом сообщения нужного чата. Это то же самое, что открыть бота в приложении и нажать на диалог. В статье — как получить

Обновлено 2 ноября 2026 г.4 мин

Чаты и сообщения через API читаются двумя запросами: сначала список чатов бота, потом сообщения нужного чата. Это то же самое, что открыть бота в приложении и нажать на диалог.

В статье — как получить список чатов и листать его страницами, найти конкретный чат, прочитать переписку и превратить id операторов, тегов и полей в понятные названия.

Что понадобится

API-ключ с ролью Space viewer или выше. Какую роль выбрать — в статье Права API-ключа: какую роль выдать.

id бота. Как его найти — в статье Первый запрос к API за 5 минут.

Получите список чатов бота

Список чатов бота отдаёт POST /chats/v1/search с bot_id в теле. Сначала идут чаты с самой свежей перепиской:

POST

https://api.chatterfy.ai/public-api/chats/v1/search

Список чатов бота

curl -X POST 'https://api.chatterfy.ai/public-api/chats/v1/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"bot_id": "ID_БОТА", "limit": 50}'

Поле	Обязательно	Что значит
`bot_id`	Да	id бота
`limit`	Нет	Сколько чатов на странице: от 1 до 100, по умолчанию 25
`sort`	Нет	`desc` — сначала чаты со свежими сообщениями (по умолчанию), `asc` — наоборот
`filter`	Нет	Условия отбора: статус, теги, даты и другие. Подробно — в статье Фильтры чатов в API
`cursor`	Нет	Метка следующей страницы из прошлого ответа

Листайте страницы списка чатов

Одна страница списка чатов — не больше 100 чатов. Следующие страницы запрашиваются через cursor и has_more:

Посмотрите на pagination

Если в ответе has_more: true, чатов больше. В next_cursor лежит метка следующей страницы.

Повторите запрос с cursor

Отправьте тот же запрос и добавьте поле cursor со значением next_cursor. Остальные поля не меняйте.

{
  "bot_id": "ID_БОТА",
  "limit": 50,
  "cursor": "ЗНАЧЕНИЕ_NEXT_CURSOR"
}

Остановитесь на последней странице

На последней странице has_more: false, а next_cursor нет.

Поиск листает до 10 000 чатов

Дальше 10 000-го чата API вернёт ошибку cursor_out_of_range. Чтобы забрать больше, используйте выгрузку — Как выгрузить все чаты через API.

Список меняется прямо во время чтения: чат с новым сообщением поднимается наверх. Если собираете чаты в таблицу, убирайте повторы по id.

Найдите конкретный чат по имени, username или id

Чтобы найти чат по имени клиента, username или Telegram id, передайте фильтр query:

{
  "bot_id": "ID_БОТА",
  "filter": { "field": "query", "value": "Анна" }
}

Список чатов берётся из поискового индекса, который отстаёт от реального состояния на секунду-другую. Чтобы получить чат точно в текущем состоянии, запросите его по id через GET /chats/v1/{chat_id}:

GET

https://api.chatterfy.ai/public-api/chats/v1/{chat_id}

Один чат по id

curl 'https://api.chatterfy.ai/public-api/chats/v1/ID_ЧАТА' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

Поля чата в ответе API

Что приходит в каждом чате из POST /chats/v1/search и GET /chats/v1/{chat_id}:

Поле	Что значит
`id`	id чата
`name`, `username`	Имя и username клиента в Telegram. Без права `chat.contacts.read` приходят скрытыми
`external_id`	id клиента в Telegram
`status`	Статус чата: `ai` — Auto, `manual` — Manual, а также `waiting`, `ignore`, `blocked`, `error`, `stopped`, `finished`. Что они значат — в статье Chat Status — статусы диалога
`assign_id`	id ответственного. Имя — в списке участников Space, ниже
`tags`	id тегов чата
`custom_fields`	Поля чата: `id` поля, его `key` и значение `value`
`last_message`	Последнее сообщение со всеми полями
`read_state.incoming_unread_count`	Сколько сообщений клиента ещё никто не прочитал
`lead`	Откуда пришёл клиент: кампания и метки Tracker. Подробнее — Аналитика и Tracker через API
`created_at`	Когда появился чат

Прочитайте сообщения чата

Сообщения одного чата отдаёт POST /messages/v1/search с chat_id в теле. Без поля type придут и сообщения, и системные события:

POST

https://api.chatterfy.ai/public-api/messages/v1/search

Сообщения одного чата

curl -X POST 'https://api.chatterfy.ai/public-api/messages/v1/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"chat_id": "ID_ЧАТА", "limit": 50, "order": "desc", "type": "message"}'

Поле	Что значит
`chat_id`	id чата. Обязательное поле
`limit`	Сколько сообщений на странице: до 100, по умолчанию 25
`order`	`desc` — сначала новые (по умолчанию), `asc` — сначала старые
`type`	`message` — только сообщения, `event` — только системные события вроде смены тега или статуса. Без этого поля придут и те, и другие
`cursor`	Метка следующей страницы

Страницы сообщений листаются так же, как страницы чатов: через cursor и has_more.

Поля сообщения в ответе API

Что приходит в каждом сообщении из POST /messages/v1/search:

{
  "id": "e1a7c3d9-4b2f-4e8a-9c6d-0f5b2a7e3c18",
  "chat_id": "9d4e1b27-3c8a-4f6e-b2d1-7a5c0e8f3b62",
  "type": "message",
  "status": "ready",
  "content": "Здравствуйте! Сколько стоит доставка?",
  "sender_type": "incoming",
  "read": true,
  "files": [],
  "created_at": "2026-10-28T09:15:42Z"
}

Поле	Что значит
`content`	Текст сообщения
`sender_type`	`incoming` — от клиента, `outcoming` — от вашей стороны
`sender`	id оператора, который отправил сообщение. Пусто, если отправил бот
`status`	`ready` — отправлено, `waiting` — отправляется, `schedule` — запланировано, `failed` — не отправлено, причина в `error`
`files`	Вложения: тип (`photo`, `document` и другие) и ссылка `url`
`reply_message_id`	id сообщения, на которое это сообщение отвечает
`is_mailing`	`true`, если сообщение пришло из рассылки
`edited_at`	Когда сообщение редактировали

Превратите id операторов, тегов и полей в названия

Люди, теги и поля в чатах и сообщениях указаны через id. Чтобы показать названия, запросите справочники:

Участники Space — POST /spaces/v1/{space_id}/members/search. space_id есть в данных бота. В ответе два списка: accounts — сотрудники и service_accounts — сервисные аккаунты.

Теги бота — GET /bots/v1/{bot_id}/tags: id, name и color каждого тега.

Поля бота — GET /bots/v1/{bot_id}/custom-fields: id, key, name и type каждого поля.

curl -X POST 'https://api.chatterfy.ai/public-api/spaces/v1/ID_SPACE/members/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

Справочники меняются редко. Запросите их один раз и храните у себя, а не перед каждым чатом.

Частые вопросы

Связанное

Фильтры чатов в API

Фильтр чатов — это условия, по которым API отбирает чаты: например, «непрочитанные», «с тегом Оплатил» или «пришли из Google». Один и тот же фильтр работает в поиске, подсчёте, выгрузке и подписке на

Как отправить сообщение клиенту через API

Отправка сообщения через API — это ответ клиенту от имени вашей интеграции. Сообщение уходит клиенту в чат с ботом, так же как ответ оператора из приложения. В статье — как отправить текст, файл, отве

Как изменить чат через API: статус, теги, ответственный, поля

Изменение чата через API — это то же, что правка карточки клиента в приложении: смена статуса, ответственного, тегов и полей. Всё делается одним запросом PATCH , в котором вы передаёте только то, что

Как выгрузить все чаты через API

Выгрузка чатов — это способ забрать все чаты бота разом: в таблицу, в свою CRM или базу данных. Она читает снимок чатов на момент начала, поэтому ничего не пропускает и не повторяет, сколько бы чатов

Эта статья была полезна?