Открытый API

Открытый API MaxBotStat позволяет читать аналитику и отправлять сообщения от имени бота из вашего кода. Его используют:

• интеграция с CRM (передача новых контактов и диалогов);
• информационные панели (выгрузка статистики);
• автоматические рассылки и ответы;
• регулярная выгрузка данных.

Базовый адрес

https://app.maxbotstat.ru/api/v1

Все методы возвращают application/json.

Авторизация

Используется ключ API в заголовке X-API-Key. Альтернатива — Authorization: Bearer:

X-API-Key: mbs_AbCd...EfGh
# или
Authorization: Bearer mbs_AbCd...EfGh

Подробнее: Авторизация.

Разрешения

Каждый ключ имеет одно или оба разрешения:

Разрешение	Что разрешено
read	чтение списков, контактов, сообщений, статистики
write	отправка сообщений и рассылок

Все методы GET требуют read. POST /broadcast и POST /send требуют write.

Методы

Метод	Путь	Описание
GET	/me	Профиль владельца ключа и активные разрешения
GET	/bots	Список всех ваших ботов
GET	/bots/{id}	Карточка бота
GET	/bots/{id}/contacts	Контакты бота (с постраничной выборкой)
GET	/bots/{id}/contacts/{userId}	Карточка контакта
GET	/bots/{id}/messages	История сообщений (фильтры по дате и пользователю)
GET	/bots/{id}/dialogs	Лента диалогов (как в кабинете)
GET	/bots/{id}/stats	Сводная статистика бота
GET	/bots/{id}/stats/timeline	Подневная динамика (входящие/исходящие/новые контакты)
GET	/bots/{id}/sources	Источники по UTM с числом контактов
GET	/bots/{id}/intents	Список намерений с метриками
POST	/bots/{id}/send	Отправить сообщение пользователю
POST	/bots/{id}/broadcast	Запустить рассылку

Идентификаторы

Везде используется публичный идентификатор бота (UUID), например 5d4e3a2b-.... Внутренние числовые номера через API не отдаются.

В заголовке HTTP подойдёт и числовой идентификатор (для обратной совместимости), но открытые интеграции должны использовать UUID.

Формат ответов

Списки

{ "data": [ ... ], "total": 412, "limit": 100, "offset": 0 }

Один объект

{ "id": "uuid", "name": "...", ... }

Ошибки

{ "message": "Описание ошибки" }

Код HTTP: 4xx — ошибки клиента, 5xx — ошибки сервера. См. Коды ошибок.

Постраничная выборка

Все списочные методы принимают:

• limit — размер страницы. По умолчанию 100, не больше 1000.
• offset — смещение. По умолчанию 0.

Поле total в ответе — общее число элементов на сервере (не зависит от limit/offset).

Производительность

Для больших выборок используйте limit=1000 и идите по страницам. Постраничной выборки по курсору пока нет.

Лимиты запросов

В текущем выпуске лимиты не строгие:

• около 60 запросов в минуту на ключ (мягкое ограничение через nginx);
• 100 одновременных открытых соединений на сервер.

Если упираетесь — пишите в поддержку, расширим квоту.

Версии

Текущая версия — v1, она стабильна. При появлении несовместимых изменений мы:

1. выпустим v2 параллельно;
2. оставим v1 минимум на 6 месяцев;
3. предупредим всех, у кого время последнего использования ключа попадает в методы v1.

Быстрый пример

# 1. выпустите ключ в кабинете (Настройки → API)
# 2. сохраните в переменную
export MBS_KEY="mbs_..."

# 3. получите список своих ботов
curl "https://app.maxbotstat.ru/api/v1/bots" \
     -H "X-API-Key: $MBS_KEY"

# 4. возьмите идентификатор первого бота и попросите его статистику
curl "https://app.maxbotstat.ru/api/v1/bots/<botId>/stats" \
     -H "X-API-Key: $MBS_KEY"