История переписки

Возвращает историю сообщений между ботом и пользователями — то же, что попадает в переписку в Telegram: входящие сообщения от пользователей и исходящие от бота. Можно смотреть переписку конкретного чата, искать по тексту сообщений и фильтровать по дате и направлению.

Запрос

Не забудьте добавить заголовок для авторизации запроса. Подробней в этом разделе

POST /v1/messages/list

Если ваш API-ключ привязан к одному боту (обычный ключ из раздела «Мои боты») — ничего дополнительно указывать не нужно.

Если вы используете ключ из раздела «API-ключи», выданный сразу на несколько ботов, в каждом запросе нужно явно указать, какого бота он касается — заголовком Resource-Key либо полем resource_key в теле запроса. Значение — публичный ключ бота (часть до двоеточия в API-ключе бота из раздела «Мои боты»).

Параметры пагинации

Параметр	Тип	По умолчанию	Описание
limit	int	20	Количество записей (макс. 500)
offset	int	0	Смещение — сколько записей пропустить с начала

Фильтры

Все фильтры необязательны и передаются прямо в теле запроса (без вложенного объекта).

Фильтр	Тип	Описание
filter_chat_id	int	Показать переписку только с одним чатом (Telegram chat_id)
filter_way	int	Направление: 1 — входящие (от пользователя), 2 — исходящие (от бота)
filter_type	string	Тип сообщения/метода, например message или sendMessage
filter_search	string	Поиск по тексту сообщения (ищет вхождение подстроки)
filter_date_from	string	Начало периода, формат YYYY-MM-DD HH:MM:SS
filter_date_to	string	Конец периода, формат YYYY-MM-DD HH:MM:SS

Если не указать filter_date_from/filter_date_to, по умолчанию возвращаются сообщения только за последние 30 дней. Чтобы получить более старую переписку, явно задайте нужный период.

Результат всегда отсортирован по дате от новых к старым — своя сортировка не поддерживается.

Пример запроса

POST /v1/messages/list
Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "limit": 20,
  "offset": 0,
  "filter_chat_id": 123456789,
  "filter_search": "промокод"
}

Ответ

{
  "ok": true,
  "data": {
    "total": 42,
    "rows": [
      {
        "id": "a1b2c3d4-...",
        "chat_id": 123456789,
        "way": 1,
        "direction": "in",
        "type": "message",
        "date": "2026-07-05 14:30:00",
        "get_date": "2026-07-05 14:30:01",
        "text": "Привет, у меня остался промокод?",
        "data": {
          "message_id": 4821,
          "text": "Привет, у меня остался промокод?"
        }
      }
    ]
  }
}

Поля ответа

Поле	Тип	Описание
total	int	Общее количество сообщений, подходящих под фильтры (без учёта limit/offset)
rows	array	Список сообщений, см. поля ниже
id	string	Внутренний идентификатор сообщения
chat_id	int	Telegram chat_id — с кем велась переписка
way	int	Направление: 1 — входящее, 2 — исходящее
direction	string	То же самое направление словами: in / out
type	string	Тип сообщения/метода (например message, sendMessage, editmessagetext и т. д.)
date	string	Дата и время сообщения
get_date	string	Дата и время, когда сообщение было получено платформой (обычно совпадает с date или чуть позже)
text	string|null	Текст сообщения. null, если в сообщении нет текста (например, это фото без подписи)
data	object	Полный исходный объект сообщения Telegram — может содержать медиа, кнопки и другие поля

data — это необработанный объект сообщения из Telegram Bot API, его состав зависит от типа сообщения (текст, фото, документ, опрос и т. д.).

Коды ошибок

Код	Описание
400	Не передан обязательный параметр либо параметр неверного формата
401	API-ключ не передан или недействителен
403	Ресурс недоступен этому ключу
500	Внутренняя ошибка сервера

Пример ошибки:

{
  "ok": false,
  "error": { "errors": "resource_key is required" },
  "error_code": 400
}