REST API → Контакты

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

Список контактов бота с пагинацией.

Scope: read

Параметры

Параметр	Тип	По умолчанию	Описание
limit	int	100	размер страницы (1–1000)
offset	int	0	смещение

Запрос

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

Ответ

{
  "data": [
    {
      "id": "9f2e...",
      "external_user_id": "123456789",
      "username": "anna",
      "first_name": "Анна",
      "last_name": "Петрова",
      "is_premium": false,
      "last_seen_at": "2026-04-30T15:23:01Z",
      "messages_count": 42
    }
  ],
  "total": 412,
  "limit": 50,
  "offset": 0
}

Контакты отсортированы по last_seen_at DESC — последние активные сверху.

GET /api/v1/bots/{id}/contacts/{userId}

Карточка одного контакта. userId — это external_user_id (id пользователя в Telegram/Max).

curl "https://capybara.maxbotstat.ru/api/v1/bots/<botId>/contacts/123456789" \
     -H "X-API-Key: $MBS_KEY"

Ответ

{
  "contact": {
    "id": "9f2e...",
    "external_user_id": "123456789",
    "username": "anna",
    "first_name": "Анна",
    "last_name": "Петрова",
    "is_premium": false,
    "phone": null,
    "last_seen_at": "2026-04-30T15:23:01Z"
  },
  "stats": {
    "total_messages": 42,
    "inbound": 31,
    "outbound": 11,
    "first_at": "2025-09-20T08:00:00Z",
    "last_at": "2026-04-30T15:23:01Z"
  },
  "attribution": {
    "source_value": "instagram",
    "campaign_name": "spring",
    "first_seen_at": "2025-09-20T08:00:00Z",
    "last_seen_at": "2025-09-20T08:00:00Z",
    "touches": 1
  }
}

Объект	Описание
contact	Метаданные пользователя
stats	Сводная статистика по перепискам
attribution	Источник трафика (UTM); null, если контакт пришёл «вне UTM»

Поиск контактов

Поиска по подстроке через REST API v1 пока нет. Альтернатива:

1. Скачайте все контакты страницами;
2. Фильтруйте на своей стороне.

Для большой базы это может быть тяжело — следите за обновлениями API. Поиск планируется в v1.1.

Связь с сообщениями

external_user_id — связующий ключ между контактами, сообщениями и атрибуцией. Используйте его в:

• GET /api/v1/bots/{id}/messages?userId=<external_user_id>
• POST /api/v1/bots/{id}/send (поле userId)

Ошибки

HTTP	Сообщение	Когда
404	Bot not found	бот не принадлежит вам
404	Contact not found	контакт с таким external_user_id бот не видел
400	bad limit/offset	вне диапазона