2026-10-26

MAX Bot API без SDK: токен, первый запрос и отправка сообщения

Коротко: MAX Bot API это HTTP-интерфейс для ботов мессенджера MAX. Запросы идут на https://platform-api2.max.ru, этот адрес действует с 19 июля 2026 года. Токен выдают в кабинете business.max.ru после модерации бота, а передают в заголовке Authorization как есть, без слова Bearer. Сервер отдаёт сертификат НУЦ Минцифры, поэтому curl и библиотеки без корня Russian Trusted Root CA падают с ошибкой сертификата. Первый запрос, который стоит сделать, это GET /me:

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

Если пришёл JSON с именем бота, токен рабочий и всё остальное настроено правильно.

Если нужен готовый бот для записи клиентов или ответов на вопросы, а разработчика нет, API напрямую не понадобится: такие боты собирают в конструкторах с поддержкой MAX. Эта статья для тех, кто пишет бота сам или подключает MAX к своему сервису.

Как создать бота в MAX и получить токен#

Ботов в MAX создают только верифицированные организации, ИП и самозанятые, резиденты России. Порядок такой:

1. Пройдите верификацию организации, ИП или самозанятого.
2. Создайте бота в кабинете business.max.ru в разделе «Чат-боты» или в мини-приложении «MAX для бизнеса».
3. Дождитесь модерации, она занимает до 48 часов в рабочие дни.
4. Скопируйте токен в настройках бота.

Токен бота MAX лежит в кабинете business.max.ru, в настройках бота, и появляется только после модерации. У организации может быть до пяти ботов, у самозанятого до двух.

Физическим лицам и нерезидентам верификация пока недоступна. Организация проходит её через Госуслуги, T‑Business ID или Alfa ID (через банки пока только в веб-версии кабинета), самозанятый только через Госуслуги. Делать это должен руководитель или тот, у кого есть право подписи.

Первый запрос#

GET /me возвращает данные бота и проверяет сразу три вещи: адрес, токен и сертификат. В документации MAX ответ выглядит примерно так:

{
  "user_id": 1,
  "first_name": "My Bot",
  "username": "my_bot",
  "is_bot": true,
  "last_activity_time": 1737500130100
}

Если вместо этого пришла ошибка, её текст подсказывает, что не так:

Передавать токен параметром ?access_token= в адресе документация MAX больше не поддерживает: способ объявлен устаревшим и может перестать работать в любой момент. Да и не стоит: адрес с токеном оседает в логах.

Зачем сертификат Минцифры#

Вместе со сменой адреса MAX попросил разработчиков добавить сертификат Минцифры в список доверенных. Сервер platform-api2.max.ru предъявляет сертификат, выданный Russian Trusted Sub CA, а этому центру по умолчанию не доверяют ни curl, ни Python, ни Node.js. Поэтому первый запрос на чистой машине часто заканчивается ошибкой сертификата.

Отключать проверку флагом -k не нужно. Поставьте корневой сертификат Russian Trusted Root CA туда, где его ищет ваш инструмент. Для curl на один запуск хватит --cacert, для Python, Node.js, Java и Docker свои способы. Все они по шагам разобраны в статье про Russian Trusted Root CA.

Как отправить сообщение#

Сообщение отправляют запросом POST /messages. Получателя указывают в адресе: user_id для личного диалога или chat_id для группы и канала. Текст и вложения идут в теле:

curl -X POST "https://platform-api2.max.ru/messages?user_id=123456" \
  -H "Authorization: $MAX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Заказ 42 собран, можно забирать", "format": "markdown"}'

Что стоит знать заранее:

• Текст до 4000 символов. Поле format принимает markdown или html.
• Кнопки добавляют вложением inline_keyboard: ссылки, обратный вызов, запрос контакта или геопозиции. Всего до 210 кнопок, 30 рядов по 7, а для ссылок, мини-приложений и запросов контакта или геопозиции по 3 в ряду.
• Лимиты: не больше 30 запросов в секунду к API, за превышение придёт 429. В один чат не больше двух сообщений в секунду, остальные стоит ставить в очередь.
• Нажатия кнопок с обратным вызовом приходят событием message_callback, ответить на них можно запросом POST /answers.
• Файлы отправляют в три шага: POST /uploads выдаёт адрес, на него загружают сам файл, а полученный токен вставляют во вложение сообщения. Если сервер ещё не обработал файл, придёт ошибка attachment.not.ready, тогда отправку повторяют чуть позже.

Где взять user_id и chat_id#

Списка чатов в API нет: метод GET /chats убрали в июне 2026 года. Идентификаторы приходят в событиях, и хранить их нужно у себя:

• bot_started приходит, когда пользователь нажал «Начать» в диалоге с ботом. В нём есть user.user_id и chat_id этого диалога.
• bot_added приходит, когда бота добавили в группу или канал. В нём есть chat_id.
• message_created приходит на каждое новое сообщение. Чат лежит в message.recipient.chat_id, автор в message.sender.user_id.

Пока бот в разработке, события удобно забирать запросом GET /updates. Он ждёт новых событий до 30 секунд (параметр timeout, максимум 90) и возвращает их вместе с marker. Этот marker передают в следующий запрос, чтобы не получить те же события снова.

Вебхук вместо опроса#

Опрос через GET /updates MAX рекомендует только для разработки и тестов, в рабочем режиме нужен вебхук. Подписка оформляется запросом POST /subscriptions:

{
  "url": "https://bot.example.ru/max/webhook",
  "update_types": ["message_created", "bot_started"],
  "secret": "s3cr3t-5ymb0ls"
}

Требования к адресу вебхука:

• Только HTTPS и только порт 443, порт в адресе не указывают.
• Сертификат от доверенного центра или сертификат Минцифры. Самоподписанные MAX не принимает с 25 мая 2026 года.
• Ответ 200 за 30 секунд. Если сервер не ответил, MAX повторит доставку до 10 раз со всё большим интервалом, а если успешных ответов нет восемь часов, сам отпишет бота.
• Секрет. От 5 до 256 символов: латиница, цифры, _ и -. Если в подписке указан secret, он приходит в заголовке X-Max-Bot-Api-Secret каждого запроса. Сверяйте его, иначе выдать себя за MAX может кто угодно.

Вебхук и опрос одновременно не работают: пока есть подписка, long polling отключён, об этом прямо сказано в описании POST /subscriptions.

Чем MAX отличается от Telegram#

При переносе бота из Telegram чаще всего путают вот что:

Документация и OpenAPI-спецификация MAX#

Официальная документация MAX Bot API лежит на dev.max.ru: методы, события, лимиты. С сентября 2026 года у неё есть машиночитаемая версия, файл schema.yaml в репозитории max-messenger/api-schema. В спецификации 33 метода, и её можно импортировать в API-клиент вместо того, чтобы набирать запросы руками.

Когда дойдёт до кода: официальные библиотеки у MAX есть для TypeScript и Go. Для Python MAX предлагает сгенерировать клиент из schema.yaml генератором openapi-python-client, только укажите prefix="", иначе к токену добавится Bearer. Сертификат нужен и там, способ для Python есть в статье про корень Минцифры.

В Tetiva это «Импорт из файла…» над деревом коллекций. Методы разложатся по папкам по тегам: bots, chats, messages, subscriptions, upload и comments. Дальше два шага:

1. Адрес. В спецификации адрес сервера записан как /, и окно импорта предупредит, что он относительный. Впишите в переменную baseUrl окружения «Max Bot API» значение https://platform-api2.max.ru.
2. Токен. Авторизация настроится сама: импорт распознаёт, что MAX ждёт токен в Authorization без префикса, и ставит тип Bearer Token с пустым префиксом. Серое Bearer в пустом поле Prefix это подсказка, а не значение: заголовок уйдёт без него. Токен впишите в секретную переменную apiKey.

Сертификат Tetiva проверяет по системному хранилищу. Если корень Минцифры в систему ещё не установлен, первый запрос закончится ошибкой проверки сертификата. На Linux и Windows она выглядит так, на macOS текст другой: x509: “*.max.ru” certificate is not trusted.

После установки корня по инструкции из статьи про Russian Trusted Root CA запрос пройдёт. На Linux клиент читает хранилище один раз за запуск, поэтому после установки его нужно перезапустить.

Шпаргалка#

• Адрес: https://platform-api2.max.ru, старые platform-api.max.ru и botapi.max.ru не используйте.
• Токен: заголовок Authorization: <токен>, без Bearer и не в адресе.
• Сертификат: корень Russian Trusted Root CA в хранилище вашего инструмента, без -k.
• Проверка: GET /me. Сообщение: POST /messages?user_id=… с {"text": "…"}.
• События: при разработке GET /updates, в рабочем режиме вебхук на HTTPS 443 с проверкой X-Max-Bot-Api-Secret.