API 11 июня 2026 · 8 минут чтения

REST API MaxBotStat: выгружаем контакты и диалоги в CRM

Кабинет — это удобно, но рано или поздно данные нужны в своей системе: в CRM, в BI, в собственном дашборде. Для этого есть REST-API v1: ключи с правами, пагинация, идемпотентные операции и подписки на события. Соберём типовую выгрузку контактов и диалогов.

CSV или API?

Если данные нужны разово — выгрузка в CSV (тариф Про) закрывает вопрос за минуту: открыли в Excel, посчитали, забыли. Но как только нужна регулярная синхронизация — контакты в CRM, диалоги в хранилище, цифры в свой дашборд — руками это делать невыносимо. Тут и нужен REST-API v1.

Ключи доступа

Доступ к API — по долгоживущим ключам с правами на чтение и запись (выдаёте отдельно, по принципу наименьших привилегий). Ключ создаётся в кабинете и передаётся в заголовке:

Authorization: Bearer $API_KEY

Для выгрузки в CRM хватит ключа только на чтение — не давайте интеграции прав больше, чем ей нужно. Подробности — в разделе про аутентификацию.

Достаём контакты

Список контактов отдаётся постранично — через курсор, чтобы не тащить всё разом:

curl "https://app.maxbotstat.ru/api/v1/contacts?limit=100" \
  -H "Authorization: Bearer $API_KEY"

В ответе — страница контактов и курсор на следующую. Идёте по курсору, пока он не опустеет. Точные имена полей и параметров — в документации по контактам; здесь код иллюстративный.

Достаём диалоги

import requests

def fetch_messages(contact_id, key):
    url = "https://app.maxbotstat.ru/api/v1/messages"
    params = {"contact_id": contact_id, "limit": 200}
    headers = {"Authorization": "Bearer " + key}
    return requests.get(url, params=params, headers=headers).json()

Идемпотентность при записи

Если через API не только читаете, но и шлёте сообщения, передавайте Idempotency-Key на операциях записи. Повторный запрос с тем же ключом не создаст дубль — важно при ретраях после таймаута, когда вы не знаете, прошёл запрос или нет.

Подписки на события вместо опроса

Дёргать API по кругу — расточительно. Лучше подписаться на события: новый контакт, новое сообщение, рассылка завершена. MaxBotStat пришлёт POST на ваш эндпоинт, как только событие случилось. Проверяйте подпись запроса, чтобы принимать только настоящие вызовы. Это разворачивает синхронизацию из «опрашиваю каждые 5 минут» в «реагирую мгновенно». См. раздел про вебхуки.

Типовой сценарий: синк в CRM

1. Подписываетесь на событие «новый контакт».
2. На входящем событии делаете upsert контакта в CRM по внешнему id.
3. Раз в сутки догоняете историю диалогов пачкой через /messages — на случай, если какое-то событие потерялось.

Связка «подписка для оперативности + периодическая сверка для надёжности» закрывает 99% задач интеграции и переживает короткие падения вашего сервиса.

API доступен на тарифе Макс — вместе с подписками на события и историей за 24 месяца.