Первый чат-бот MAX через API: от токена до ответа

Обновлено 20 октября 2026 г.2 мин

Короткая дорожная карта для разработчика. Все адреса и ограничения — из документации dev.max.ru.

1. Проверьте, можно ли вам создать бота

Бота создают только с верифицированным профилем организации, ИП или самозанятого — резидента РФ. Физлица и нерезиденты пока не проходят верификацию (dev.max.ru).
Лимит: 5 ботов для юрлица или ИП, 2 для самозанятого (справка для партнёров).

Как подключиться: стать партнёром, пройти верификацию.

2. Создайте бота и возьмите токен

На платформе для партнёров откройте Чат-боты → Создать и заполните карточку.
Дождитесь модерации: пользователи видят бота только после неё.
Скопируйте токен: Чат-боты → ⋮ → Настройки → значок копирования у поля токена (dev.max.ru).

Токен не публикуйте и не храните в репозитории: с ним можно управлять ботом, а за нарушение правил платформы его могут отозвать. Утёк — обновите токен.

3. Проверьте токен

Базовый адрес API — https://platform-api2.max.ru. Старый домен platform-api.max.ru заменён, а токен передаётся только в заголовке Authorization — через параметр в адресе больше не принимается (dev.max.ru).

curl "https://platform-api2.max.ru/me" \
  -H "Authorization: $MAX_BOT_TOKEN"

В ответ придут данные бота. Документация также просит добавить сертификат Минцифры в список доверенных.

4. Получите первое событие (для тестов)

Для разработки подойдёт Long Polling:

curl "https://platform-api2.max.ru/updates?timeout=30" \
  -H "Authorization: $MAX_BOT_TOKEN"

Откройте бота в MAX и запустите его. Когда пользователь запускает бота, приходит событие bot_started с полями chat_id и user.user_id (dev.max.ru).

Передавайте в следующий запрос значение marker из ответа — иначе получите только последнее обновление (GET /updates).

5. Ответьте пользователю

curl -X POST "https://platform-api2.max.ru/messages?user_id=USER_ID" \
  -H "Authorization: $MAX_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Привет! Бот работает."}'

Для группы или канала вместо user_id укажите chat_id. Ограничения: текст до 4000 символов, не больше 2 сообщений в секунду в один чат (POST /messages).

6. Перед запуском перейдите на Webhook

Long Polling ограничен по скорости и сроку хранения событий и не подходит для продакшена (GET /updates). Подпишитесь на события:

curl -X POST "https://platform-api2.max.ru/subscriptions" \
  -H "Authorization: $MAX_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.ru/webhook", "update_types": ["message_created", "bot_started"], "secret": "длинная-случайная-строка"}'

Требования к адресу (POST /subscriptions):

только HTTPS на порту 443, сертификат доверенного центра или Минцифры, без самоподписанных;
ответ 200 за 30 секунд;
при активной подписке Long Polling не работает.

Не приходят события — разбор причин. Разница подходов: Long Polling и Webhook.

7. Дальше

Общий лимит — 30 запросов в секунду к platform-api2.max.ru (dev.max.ru).
Официальные библиотеки — JavaScript/TypeScript и Go, есть спецификация OpenAPI для генерации клиента. Примеры: где найти код.
Бот в группе по умолчанию запрещён: разрешите в настройках приватности бота и выдайте права read_all_messages и write — инструкция.
Запуск с параметром — диплинк https://max.ru/<ник_бота>?start=<payload>, payload до 128 символов: диплинки для ботов.
Кнопки под сообщениями — типы, лимиты и ответ на нажатие: inline-клавиатура бота.

Все материалы для разработчиков собраны в разделе «Разработчикам».

Недавние запросы

Часто ищут

Разделы