Как получить токен бота в MAX и подключить API в 2026 году

Токен бота MAX — секретный ключ, который позволяет серверу обращаться к API от имени бота. Он появляется только после успешной модерации и используется для отправки сообщений, получения информации о боте, настройки подписок на события и других методов.

В 2026 году запросы нужно отправлять на https://platform-api2.max.ru, а токен — передавать в заголовке Authorization. Передача токена через query-параметры больше не поддерживается.

Что нужно до получения токена

1. Верифицированный профиль организации, ИП или самозанятого.
2. Созданная карточка чат-бота.
3. Успешно пройденная модерация.

После проверки откройте на платформе:

Чат-боты → Перейти → Расширенные настройки → Настроить.

Токен отображается в одноимённом поле. В этом же разделе его можно обновить и подключить URL Mini App.

Как использовать токен

Токен передаётся в каждом запросе к API:

curl --request GET \
  --url https://platform-api2.max.ru/me \
  --header "Authorization: YOUR_BOT_TOKEN"

Не добавляйте Bearer, если конкретная версия документации метода не требует этого отдельно: в общем описании API используется формат Authorization: <token>.

Успешный запрос возвращает JSON. При неверном или отозванном токене API ответит кодом 401.

Где хранить токен

Допустимые варианты:

• переменная окружения на сервере;
• секрет-менеджер облачной платформы;
• защищённый конфигурационный сервис;
• система управления секретами компании.

Токен нельзя:

• включать в код frontend;
• хранить в публичном Git-репозитории;
• передавать в URL;
• публиковать в документации и логах;
• отправлять в открытом командном чате;
• встраивать в мобильное или Mini App приложение.

Frontend должен обращаться к собственному backend, а уже backend — к API MAX.

Как настроить Webhook

Для production рекомендуется Webhook. Сервер подписывается на события через POST /subscriptions и указывает HTTPS-адрес обработчика.

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

curl --request POST \
  --url https://platform-api2.max.ru/subscriptions \
  --header "Authorization: YOUR_BOT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"url":"https://example.com/api/max/webhook","update_types":["message_created","bot_started"],"secret":"YOUR_WEBHOOK_SECRET"}'

Платформа принимает production-вебхуки только по HTTPS на порту 443 с доверенным сертификатом. Самоподписные сертификаты не поддерживаются. Endpoint должен вернуть HTTP 200 не позднее чем за 30 секунд; на своей стороне нужно проверять секрет из заголовка X-Max-Bot-Api-Secret.

Webhook или Long Polling

Long Polling допустим для локальной разработки и быстрых тестов. Использовать его одновременно с Webhook нельзя.

Актуальные изменения API в 2026 году

При разработке учитывайте:

• рабочий домен API — platform-api2.max.ru;
• токен передаётся только через Authorization;
• production-вебхуки работают по HTTPS с доверенными сертификатами;
• Long Polling не подходит для production;
• максимальная рекомендуемая нагрузка на API — 30 запросов в секунду;
• устаревший GET /chats больше не следует использовать; идентификаторы чатов и каналов получают из событий подписки;
• для получения событий используются подписки через /subscriptions.

Проверяйте обзор API MAX и историю изменений перед каждым релизом.

Как строить обработчик Webhook

Production-обработчик должен:

1. Принять HTTPS-запрос.
2. Проверить структуру и обязательные поля.
3. Зафиксировать идентификатор события.
4. Быстро вернуть успешный HTTP-ответ.
5. Передать тяжёлую обработку в очередь при необходимости.
6. Безопасно повторить обращение к внешней системе.
7. Не создать дубль при повторной доставке.
8. Записать технический результат без лишних персональных данных.

Не выполняйте долгий запрос к AI, CRM и 1С синхронно до ответа Webhook, если есть риск таймаута. Лучше подтвердить приём и продолжить обработку асинхронно.

Идемпотентность

Сетевые события могут доставляться повторно. Для операций с бизнес-эффектом — создание заказа, лида, записи или платежа — храните идентификатор события или собственный idempotency key.

Повторная обработка должна возвращать уже созданный результат, а не выполнять действие второй раз.

Ограничение частоты запросов

API может отвечать 429, если лимит превышен. Приложение должно:

• ограничивать параллелизм;
• использовать очередь;
• повторять запрос с задержкой;
• учитывать Retry-After, если он возвращается;
• не создавать бесконечный цикл повторов;
• мониторить рост ошибок.

Статусы и справочные данные лучше кешировать, если это не нарушает актуальность процесса.

Обновление токена

Токен следует обновить, если:

• он попал в репозиторий или лог;
• сотрудник или подрядчик потерял право доступа;
• есть подозрение на несанкционированное использование;
• выполняется плановая ротация секретов.

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

План ротации:

1. Найти все сервисы, использующие токен.
2. Создать окно изменения.
3. Обновить токен на платформе.
4. Заменить секрет в production и резервных процессах.
5. Перезапустить сервисы при необходимости.
6. Проверить /me, Webhook и отправку сообщения.
7. Убедиться, что старый ключ отклоняется.

Логи и мониторинг

В логах полезно хранить:

• время и тип события;
• внутренний correlation ID;
• результат обработки;
• код ответа MAX;
• продолжительность;
• количество повторов.

Не записывайте токен, полный контакт пользователя и содержимое чувствительных сообщений без необходимости. Для диагностики используйте маскирование.

Настройте уведомления по росту 401, 429, 5xx, таймаутов и необработанных событий.

Частые ошибки

• Передавать токен в query-параметре.
• Использовать старый домен API.
• Хранить ключ в frontend bundle.
• Использовать Long Polling в production.
• Не обрабатывать повторное событие.
• Повторять запросы без задержки и лимита.
• Логировать заголовок Authorization.
• Не проверять работу после ротации.
• Считать HTTP 200 от внешней системы достаточным без проверки тела ответа.

Частые вопросы

Можно ли получить токен до модерации?

Нет. Расширенные настройки и токен становятся доступны после успешной проверки бота.

Нужно ли использовать Bearer?

Общее описание API MAX указывает формат Authorization: <token>. Перед реализацией конкретного метода сверяйтесь с его актуальной документацией.

Можно ли использовать токен прямо в Mini App?

Нет. Пользователь может извлечь секрет из клиентского кода. Все запросы с токеном выполняются на backend.

Как проверить, что токен работает?

Выполнить серверный запрос информации о боте через /me и проверить успешный ответ. Не вставляйте реальный токен в публичные онлайн-инструменты.

Что делать после утечки токена?

Немедленно обновить его на платформе, заменить во всех средах, проверить логи и убедиться, что от имени бота не выполнялись посторонние действия.