API MAX — интерфейс, через который бот работает с мессенджером: HTTPS-запросы на platform-api2.max.ru с токеном бота в заголовке Authorization, ответы — в JSON. Токен выдаёт платформа MAX для партнёров после модерации бота, а подключиться к ней могут только юрлица, ИП и самозанятые — резиденты РФ. Ниже — как получить токен, сделать первый запрос, принимать события через Webhook или Long Polling, какие у API лимиты и на чём писать бота: официальные библиотеки есть для JavaScript/TypeScript и Go.

Кто может получить токен API MAX

Подключение к платформе MAX для партнёров и её сервисам — чат-ботам, мини-приложениям, каналам — доступно юрлицам, ИП и самозанятым, которые являются резидентами РФ. Физические лица и нерезиденты пока не смогут пройти верификацию на платформе. Бота можно создать, только если у вас есть верифицированный профиль организации, ИП или самозанятого.

Тип профиля	Сколько ботов можно создать
Организация или ИП	5
Самозанятый	2

Как зарегистрироваться на business.max.ru и пройти верификацию через Госуслуги или банк — в статье «MAX для партнёров: регистрация и верификация». Если вы ищете, как найти и запустить чужого бота, а не написать своего, — это статья «Как создать чат-бота в MAX и найти готовых ботов».

Как получить токен бота MAX

Токен бота становится доступен после того, как бот пройдёт модерацию.

Перейдите в профиль на платформе MAX для партнёров.
В разделе Чат-боты нажмите Создать.
Заполните карточку. Логотип — 500 × 500 px, не более 5 МБ, соотношение 1:1, .jpg, .jpeg или .png. Название — от 1 до 59 символов: латиница, кириллица, цифры, без эмодзи. Описание — не более 200 символов. Никнейм создаётся автоматически: idИНН_bot для ИП и юрлиц, se(orgid)_bot для самозанятых; выбрать или изменить его пока нельзя.
Нажмите Создать — бот уйдёт на модерацию. Проверка занимает до 48 часов по рабочим дням, о смене статуса пишет бот MAX для бизнеса.
После успешной модерации откройте Чат-боты → выберите бота → ⋮ → Настройки и нажмите на значок копирования справа от поля с токеном.

Статусы модерации: «На модерации» — настройки менять нельзя; «Опубликован» — бот доступен пользователям; «Нужны исправления» — причина отказа написана в карточке бота, после правки данные отправляют на проверку повторно.

Если вы верифицировали профиль и создали бота в мини-приложении «MAX для бизнеса», токен можно взять там же или в боте «MAX для бизнеса» командой Получить токен.

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

Первый запрос к API MAX

Базовый адрес — https://platform-api2.max.ru/. С 19 июля 2026 года запросы нужно направлять на него, а не на прежний platform-api.max.ru, и добавить сертификат Минцифры в список доверенных. Токен передаётся только в заголовке Authorization: <access_token>: передача через query-параметры больше не поддерживается.

Если запрос падает с ошибкой сертификата (у curl — SSL certificate problem), скорее всего, сертификат Минцифры не добавлен в доверенные. Node.js по умолчанию не читает системное хранилище сертификатов: путь к файлу сертификата передают в переменной окружения NODE_EXTRA_CA_CERTS.

Проверьте токен методом GET /me — он вернёт информацию о боте:

curl -X GET "https://platform-api2.max.ru/me" \
  -H "Authorization: {access_token}"

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

HTTP-метод запроса задаёт операцию: GET — получить ресурсы, POST — создать (например, отправить сообщение), PUT — редактировать, DELETE — удалить, PATCH — исправить. Кроме JSON сервер возвращает код ответа:

Код	Значение
200	успешный запрос
400	недействительный запрос
401	ошибка аутентификации
404	ресурс не найден
405	метод не допускается
429	превышено количество запросов
503	сервис недоступен

Лимиты API MAX

Что	Ограничение
Запросы к `platform-api2.max.ru`	30 в секунду
Сообщения в один диалог, групповой чат или канал	не более 2 в секунду
Текст сообщения	до 4 000 символов
Inline-клавиатура	до 210 кнопок в 30 рядах, до 7 в ряду; кнопок `link`, `open_app`, `request_geo_location`, `request_contact` — до 3 в ряду
Изображение	до 50 МБ и не более 7680 × 7680 px — оба условия сразу
Видео	до 250 МБ
Аудио	до 256 МБ и не более 60 минут — оба условия сразу
Файл	до 4 ГБ
Видео, изображения и клавиатура в одном сообщении	всего не более 12 вложений, вложение с кнопками тоже считается

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

Webhook или Long Polling: как бот получает события

Для production-окружения — только Webhook. Для разработки и тестирования — Webhook или Long Polling. Использовать оба способа одновременно нельзя.

Webhook после новых действий в чат-боте сам отправляет запрос на ваш сервер; для него нужен публичный сервер с HTTPS и статичным IP-адресом. Long Polling — это периодические запросы бота к серверу, внешний сервер со статичным IP ему не нужен. Но он ограничен по скорости и сроку хранения событий и малоэффективен при высокой интенсивности обновлений.

Как подключить Webhook: POST /subscriptions

curl -X POST "https://platform-api2.max.ru/subscriptions" \
  -H "Authorization: {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://<ваш-домен>/webhook",
  "update_types": ["message_created", "bot_started"],
  "secret": "<ваш-секрет>"
}'

Требования к вашему endpoint:

HTTPS и только порт 443; порт в URL не указывается;
TLS-сертификат от доверенного центра сертификации или сертификат Минцифры; с 25 мая вебхуки по HTTP и самоподписанные сертификаты не поддерживаются;
доменное имя в URL совпадает с CN или SAN сертификата, сервер отдаёт полную цепочку сертификатов;
ответ HTTP 200 в течение 30 секунд — любой другой код или тайм-аут считается ошибкой доставки.

Параметр secret — от 5 до 256 символов: латиница, цифры и дефис. Подходящий генерирует команда openssl rand -hex 32; строка base64 с +, / и = не подойдёт. Если секрет задан, MAX передаёт его в заголовке X-Max-Bot-Api-Secret каждого запроса: проверяйте заголовок и отклоняйте запросы при несовпадении. Код 200 на сам POST /subscriptions ещё не значит, что подписка создана: смотрите поле success в ответе, при ошибке там false, а причина — в message.

Если доставка не удалась, MAX делает до 10 повторных попыток с растущим интервалом: через 60 секунд, через 150, через 375 и так далее. Если за 8 часов endpoint ни разу не ответил успешно, бот автоматически от него отписывается. Список подписок возвращает GET /subscriptions, отписаться — DELETE /subscriptions?url=…; после отписки становится доступен Long Polling. Если уведомления не приходят, FAQ платформы называет две причины: не работает сервер бота или есть проблемы с сетью.

Отвечайте 200 сразу, а событие обрабатывайте после ответа — в таком порядке шаги идут и в модели доставки из документации. Если обработка не уложится в 30 секунд, MAX сочтёт доставку неудачной и пришлёт событие повторно — бот может ответить на него дважды. После автоматической отписки события перестанут приходить, пока вы снова не вызовете POST /subscriptions.

Long Polling: GET /updates

curl -X GET "https://platform-api2.max.ru/updates" \
  -H "Authorization: {access_token}"

Параметр	Значение
`limit`	от 1 до 1000, по умолчанию 100 — сколько обновлений вернуть
`timeout`	от 0 до 90 секунд, по умолчанию 30
`marker`	номер следующего ожидаемого обновления из прошлого ответа
`types`	какие события получать, например `message_created,message_callback`

После того как вы передали marker, все предыдущие обновления считаются прочитанными. Без marker придёт только последнее обновление. Чтобы получать события из групповых чатов и каналов, бот должен быть в них администратором — как назначить бота админом канала, описано в статье «Как добавить бота в канал MAX».

Какие события присылает MAX

bot_started — пользователь впервые начал общение с ботом или возобновил его после остановки;
bot_stopped — пользователь остановил или удалил бота;
bot_added и bot_removed — бота добавили в чат или канал либо удалили оттуда;
message_created, message_edited, message_removed — новое, отредактированное или удалённое сообщение или пост;
message_callback — пользователь нажал на кнопку;
user_added, user_removed — участник пришёл в чат или канал либо ушёл;
dialog_muted, dialog_unmuted, dialog_cleared, dialog_removed — пользователь отключил или включил уведомления, очистил или удалил диалог с ботом;
comment_created, comment_edited, comment_removed — комментарии к постам;
chat_title_changed и bot_admin_permissions_changed — новое название чата, новые права бота.

FAQ платформы пишет, что отслеживать настройки уведомлений пользователя разработчики пока не могут; при этом события dialog_muted и dialog_unmuted из списка выше приходят, когда пользователь отключает или включает уведомления в диалоге с ботом. Что видит в настройках сам пользователь — в статье «Уведомления в MAX».

Как узнать chat_id и отправить сообщение

chat_id нужен большинству методов, которые работают с конкретным чатом. Для чата или канала его можно получить только через подписку: он приходит в объекте Update на выбранные события, например bot_added или bot_started. Метод GET /chats с июня 2026 года не поддерживается, поэтому хранить идентификаторы придётся самим: сохранять chat_id из событий, обрабатывать дубли и удалять его при bot_removed.

Сообщение отправляет POST /messages — пользователю с параметром user_id или в чат и канал с chat_id:

curl -X POST "https://platform-api2.max.ru/messages?user_id={user_id}" \
  -H "Authorization: {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"text": "Это сообщение с кнопкой-ссылкой", "attachments": [{"type": "inline_keyboard",
  "payload": {"buttons": [[{"type": "link", "text": "Откройте сайт", "url": "https://example.com"}]]}}]}'

В теле можно указать format — markdown или html — и notify: false — отправить без push-уведомлений (для каналов нельзя). Превью ссылок отключает query-параметр disable_link_preview=true: он передаётся в адресе рядом с user_id или chat_id.

Тип кнопки	Что делает
`callback`	присылает боту событие `message_callback`
`link`	открывает ссылку до 2048 символов
`request_contact`	запрашивает контакт и номер телефона пользователя
`request_geo_location`	запрашивает местоположение
`open_app`	открывает мини-приложение внутри бота
`message`	отправляет боту заранее заданный текст
`clipboard`	копирует текст из `payload` в буфер обмена

Если переслать сообщение с кнопками из бота в другой чат, кнопки не перешлются. Как подключить мини-приложение для кнопки open_app — в статье «Мини-приложения в MAX».

Что изменилось в API MAX в 2026 году

Июнь — метод GET /chats удалён; в POST /uploads добавлены ограничения на видео, аудио, изображения и файлы.
Июль — новый метод PATCH /me/commands для команд бота; с 19 июля — домен platform-api2.max.ru и сертификат Минцифры.
Август — методы и события для комментариев к постам в каналах; параметр description в PATCH /chats/{chatId}.
Сентябрь — спецификация OpenAPI на GitHub; с 9 сентября ограничен POST /chats/{chatId}/members, с 30 сентября метод удаляется, и готовой возможности добавлять участников в групповой чат API не даёт.

Бот для MAX на JavaScript, Go и Python

Официальных библиотек MAX Bot API две: для TypeScript и JavaScript и для Go.

JavaScript. Установите пакет — npm install --save @maxhub/max-bot-api (есть варианты для yarn, pnpm и deno), создайте bot.js и передайте токен через переменную окружения:

import { Bot } from '@maxhub/max-bot-api';
const bot = new Bot(process.env.BOT_TOKEN);
bot.command('start', (ctx) => ctx.reply('Добро пожаловать!'));
bot.on('message_created', (ctx) => ctx.reply('Новое сообщение'));
bot.start();

Запуск — BOT_TOKEN="<your_token_here>" node bot.js. Сообщения вне обработчиков отправляют методы bot.api.sendMessageToUser и bot.api.sendMessageToChat, а метод, которого нет в библиотеке, вызывается через ctx.api.raw.

Если бот уже подписан на Webhook, Long Polling не работает, пока подписка активна, и бот из примера может не получать событий: проверьте GET /subscriptions и при необходимости отпишитесь через DELETE /subscriptions.

Go. Модуль ставится командой go get github.com/max-messenger/max-bot-api-client-go, объект API создаётся вызовом maxbot.New(os.Getenv("TOKEN")). Для обработки сообщений, команд и callback-запросов есть Golang-фреймворк — репозиторий max-messenger/maxbot. Документация советует передавать токен через переменные окружения, а не хранить его в коде.

Python и другие языки. Официальной библиотеки на Python документация не называет. Вместо неё есть спецификация OpenAPI в формате .YAML — репозиторий max-messenger/api-schema на GitHub: по ней генератор кода собирает готовый клиент на Python, C#, PHP, Java, Swift или Kotlin. Спецификация описывает параметры кратко, подробности — в описании методов. Можно обойтись и без клиента: API — обычные HTTPS-запросы, как в примерах curl выше.

Готовые примеры — демобот max-messenger/demo-bot-go и бот-список дел max-messenger/max-bot-example-todolist. Команд по умолчанию у ботов нет: их задаёт разработчик, метод — PATCH /me/commands. Без программирования сценарий собирают в конструкторах официальных партнёров MAX — на сайте партнёра, с компьютера. Какие боты уже работают в MAX, смотрите в каталоге ботов и в категориях «Утилиты», «Админ-инструменты» и «Бизнес и услуги»; обзор — в статье «Боты в MAX: сколько их и какие бывают».

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

Может ли физическое лицо получить токен? Нет. Верификация на платформе доступна юрлицам, ИП и самозанятым — резидентам РФ.

Можно ли сделать непубличного бота? Нет: пользователи могут найти любого бота по ссылке или по никнейму через поиск.

Можно ли передать бота другому владельцу? Поменять владельца или передать права на управление ботом пока нельзя.

Можно ли создать канал через API? Документация API такого метода не описывает; каналы для бизнеса создаются через платформу — см. статью «Как создать канал в MAX».

Данные о каналах MAX через API gosmax.ru

Если боту или сервису нужны данные о каналах MAX, у нашего каталога есть свой API. Открытые JSON-эндпоинты — поиск по каталогу, категории, тренды роста и датасет-экспорт — работают без ключей и регистрации; те же данные на сайте — категории и тренды роста. Ряд подписчиков, который мы измеряем сами на max.ru, отдаёт GET /api/v1/history с ключом в заголовке X-Api-Key на тарифе Business (тарифы). CORS не настроен, данные забирают server-to-server. Описание эндпоинтов — на странице API каталога, тестовый ключ — через форму «Тестовый ключ к API» внизу той же страницы.

Источники

Страницы документации для разработчиков MAX, по которым собрана статья:

Как мы это проверили

Документацию dev.max.ru — разделы /docs, /docs-api и FAQ, 93 страницы — мы выгрузили 26 сентября 2026 года и сверили с ней каждый шаг, лимит и дату. Примеры кода взяты из документации, сокращены и не изменены по смыслу. Чего в документации нет — официальной библиотеки на Python, цены доступа к API, лимитов скорости Long Polling и срока хранения событий в нём, — в статье не утверждается. Как устроен наш каталог, описано в методологии и на странице о проекте, найти бота или канал можно через поиск.

API MAX для ботов: токен, первый запрос, вебхук и библиотеки