Короткий ответ: бот в MAX работает через HTTPS-запросы к домену platform-api2.max.ru. Токен выдаётся при создании бота на платформе для бизнеса, передаётся в заголовке Authorization и не должен попадать в query-параметры — этот способ передачи больше не поддерживается. События можно получать двумя способами: вебхуком через POST /subscriptions или длинным опросом через GET /updates.
Бизнес-часть — зачем это нужно и какие сценарии окупаются — описана на странице услуги разработки ботов MAX. Ниже техническая настройка: от получения токена до проверки подписки на события.
Шаг 1. Получить токен бота
Токен присваивается при создании бота и доступен в разделе Чат-боты → Настройки на платформе для бизнеса. Если профиль верифицирован и бот создан через мини-приложение «MAX для бизнеса», токен можно получить там же или командой Получить токен у соответствующего бота.
Токен даёт полный доступ к управлению ботом, поэтому хранится в переменных окружения или в менеджере секретов, но не в коде и не в репозитории. При компрометации токен отзывается.
Шаг 2. Проверить доступ
Самый простой способ убедиться, что всё настроено верно, — запросить информацию о боте:
curl -X GET "https://platform-api2.max.ru/me"
-H "Authorization: {access_token}"Успешный ответ содержит идентификатор бота, имя и признак is_bot. Если вместо этого приходит 401 — проблема в токене, если 404 — в адресе.
Шаг 3. Выбрать способ получения событий
| Способ | Как работает | Когда подходит |
|---|---|---|
| Вебхук | Платформа сама отправляет события на ваш HTTPS-адрес | Рабочая нагрузка: мгновенная реакция, не нужно держать постоянное соединение |
| Длинный опрос | Сервер сам запрашивает GET /updates и ждёт появления событий |
Разработка, отладка, небольшие нагрузки без публичного адреса |
Для рабочего бота выбирают вебхук: он не требует постоянно работающего процесса и реагирует сразу. Длинный опрос удобен на этапе отладки, когда публичного HTTPS-адреса ещё нет.
Шаг 4. Подписаться на события
Подписка оформляется методом POST /subscriptions, где указывается адрес обработчика и список типов событий. Управление подписками — это три метода:
| Метод | Назначение |
|---|---|
POST /subscriptions |
Подписаться на обновления |
GET /subscriptions |
Посмотреть активные подписки |
DELETE /subscriptions |
Отписаться |
Проверка подписки через GET — обязательный шаг после настройки. Она показывает, что адрес обработчика принят платформой и события действительно будут приходить.
Шаг 5. Подготовить сервер
Обработчик событий — обычный HTTPS-эндпоинт. На практике это тот же контур, что и для других мессенджеров: домен, сертификат, веб-сервер и приложение. Настройка вебхука на nginx с сертификатом разобрана в материале про вебхук Telegram-бота через nginx и SSL — схема та же, отличается только адрес платформы.
Отдельно стоит учесть требование платформы: запросы направляются на домен platform-api2.max.ru, а в список доверенных сертификатов нужно добавить сертификат Минцифры. Без этого часть запросов из вашего окружения будет завершаться ошибкой проверки сертификата.
Коды ответов и что они значат
| Код | Причина |
|---|---|
200 |
Запрос выполнен |
400 |
Некорректный запрос: проверьте тело и параметры |
401 |
Ошибка аутентификации: токен отсутствует, отозван или передан не в заголовке |
404 |
Ресурс не найден: чаще всего неверный адрес метода |
429 |
Превышено количество запросов — нужна очередь и повтор с задержкой |
503 |
Сервис недоступен — повторить позже |
Код 429 — самый частый источник проблем в ботах, которые рассылают уведомления. Отправка должна идти через очередь с ограничением скорости, а не циклом по списку получателей.
Инструменты разработчика
Платформа публикует спецификацию OpenAPI, из которой генератором кода можно получить готовые модели и функции вызова для нужного языка. Для JavaScript, TypeScript и Golang есть официальные библиотеки — они закрывают типовые операции и избавляют от ручного разбора JSON.
Порядок запуска
- Создать бота и сохранить токен вне кода.
- Проверить доступ методом
GET /me. - Поднять HTTPS-эндпоинт для приёма событий.
- Оформить подписку и проверить её методом
GET /subscriptions. - Реализовать сценарии: приветствие, меню, квалификация, передача оператору.
- Добавить журналирование и обработку
429через очередь. - Подключить передачу заявок в CRM — это отдельная задача, описанная в разделе интеграции CRM.
Диалоговую логику стоит писать так, чтобы её можно было перенести в другой канал: сценарии, база знаний и правила передачи оператору не зависят от мессенджера. Тогда второй канал — Telegram или VK — обойдётся заметно дешевле первого.