REST API → Сообщения и диалоги

GET /api/v1/bots/{id}/messages

История сообщений бота. По умолчанию — последние 100 во всех диалогах.

Scope: read

Параметры

Параметр	Тип	По умолчанию	Описание
limit	int	100	1–1000
userId	string	—	фильтр по external_user_id
from	ISO 8601 / date	—	сообщения не раньше
to	ISO 8601 / date	—	сообщения не позже

Примеры

# последние 100 сообщений
curl "https://capybara.maxbotstat.ru/api/v1/bots/<botId>/messages" \
     -H "X-API-Key: $MBS_KEY"

# переписка с конкретным пользователем
curl "https://capybara.maxbotstat.ru/api/v1/bots/<botId>/messages?userId=123456789&limit=500" \
     -H "X-API-Key: $MBS_KEY"

# за прошлый месяц
curl "https://capybara.maxbotstat.ru/api/v1/bots/<botId>/messages?from=2026-04-01&to=2026-04-30&limit=1000" \
     -H "X-API-Key: $MBS_KEY"

Ответ

{
  "data": [
    {
      "id": "5d31...",
      "direction": "in",
      "external_user_id": "123456789",
      "text": "/start utm_source=instagram",
      "created_at": "2026-04-30T15:23:01Z"
    },
    {
      "id": "a4b2...",
      "direction": "out",
      "external_user_id": "123456789",
      "text": "Здравствуйте! Чем помочь?",
      "created_at": "2026-04-30T15:23:05Z"
    }
  ],
  "limit": 100
}

Сортировка — created_at DESC (новые сверху).

Без raw_json

Поле raw_json (исходный апдейт Telegram/Max) через REST API не отдаётся для экономии трафика. Если нужно — оно доступно администратору в дебаг-режиме.

GET /api/v1/bots/{id}/dialogs

Список диалогов в порядке последнего сообщения. Удобно для отображения inbox-списка в собственном UI.

curl "https://capybara.maxbotstat.ru/api/v1/bots/<botId>/dialogs?limit=50" \
     -H "X-API-Key: $MBS_KEY"

Ответ

{
  "data": [
    {
      "id": "9f2e...",
      "external_user_id": "123456789",
      "username": "anna",
      "first_name": "Анна",
      "last_name": "Петрова",
      "last_text": "Спасибо!",
      "last_direction": "in",
      "last_at": "2026-04-30T15:23:01Z",
      "messages_total": 42
    }
  ],
  "limit": 50
}

Поле	Описание
last_text	первые 200 символов последнего сообщения
last_direction	in (от пользователя) или out (от бота)
last_at	время последнего сообщения
messages_total	общее число сообщений в этом диалоге

Полнотекстовый поиск

В REST API v1 поиска по тексту сообщений пока нет. Если нужно искать по тексту:

1. Загрузите сообщения в свою БД через периодический выгруз;
2. Используйте Postgres tsvector, ElasticSearch или Meilisearch.

Лимиты

• limit обрезается до 1000.
• Запрос с userId для несуществующего контакта вернёт пустой data (не ошибка).
• При очень большом периоде используйте пагинацию по диапазонам created_at, увеличивая from в каждом следующем запросе.