Создание бота в MAX: пошаговый разбор API, SDK и архитектуры
MAX — это российский мессенджер от VK, который в 2025 году получил статус национальной платформы и начал активно конкурировать с Telegram в сегменте бизнес-коммуникаций. Аудитория сервиса стремительно растёт на фоне ограничений Telegram в России, и для компаний это уникальное окно возможностей: занять нишу раньше, чем на платформу придут конкуренты. Чат-боты здесь — ключевой инструмент автоматизации: они умеют отвечать на вопросы, принимать заявки, проводить квалификацию лидов и отправлять уведомления без участия живого оператора.
MAX Bot API построен по принципу REST: бот отправляет HTTP-запросы на platform-api.max.ru и получает в ответ JSON с данными о пользователях, сообщениях и событиях. Концептуально это очень близко к Telegram Bot API, однако между платформами немало принципиальных отличий — как в хорошую сторону (больше кнопок, больше лимит файлов), так и в ограничительную (нет inline-режима, обязательная верификация юрлица). Понимание этих различий с самого начала сэкономит десятки часов отладки и переработки архитектуры.
Чтобы не быть голословными, покажем живой пример. Бот для розыгрышей в MAX — бесплатный инструмент без рекламы, который проверяет подписку участников и автоматически определяет победителей, исключая ручной подсчёт и накрутки. Именно такие сценарии — органический рост аудитории с минимальным участием оператора — и делают MAX перспективной площадкой для бизнеса прямо сейчас. Отправьте /start, чтобы запустить бота.
Ограничения и требования платформы
Первое, с чем сталкивается каждый разработчик, — жёсткое требование верификации. Публиковать ботов в МАКС могут только юридические лица или индивидуальные предприниматели, зарегистрированные в России. Физическим лицам и нерезидентам доступ к публикации закрыт, и обходных путей на официальном уровне не предусмотрено. Это означает, что если вы фрилансер без ИП, придётся либо оформить статус, либо работать через юридическое лицо клиента.
На одну верифицированную организацию разрешено создать не более пяти ботов. Ник бота не выбирается свободно: платформа автоматически генерирует его по шаблону idИНН_bot, и изменить это значение невозможно ни через интерфейс, ни через API. Каждый новый бот проходит модерацию — команда MAX проверяет название, описание и категорию бота, прежде чем тот станет доступен пользователям. Любое изменение в настройках запускает повторную модерацию, поэтому массовые итерации в продакшене нежелательны.
Технический лимит на запросы к API составляет 30 запросов в секунду. При превышении платформа возвращает ошибку 429 Too Many Requests. В нагруженных проектах это требует заблаговременного проектирования очереди сообщений с экспоненциальной задержкой при повторных попытках — иначе бот под нагрузкой начнёт «пропускать» события.
Регистрация и получение токена
Путь начинается на портале dev.max.ru — это Developer Portal, через который организации регистрируют проекты и получают API-ключи. Вход осуществляется через VK ID; если у вас уже есть аккаунт VK, отдельной регистрации не потребуется. После входа нужно создать новый проект: указать название, описание и категорию бота, а затем отправить заявку на модерацию.
Когда модерация пройдена, в разделе «Чат-боты → Интеграция» появляется кнопка «Получить токен». Этот токен — длинная строка вроде AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw — является единственным способом авторизовать запросы к API. Он передаётся в заголовке каждого HTTP-запроса: Authorization: ваш_токен. Потеря или компрометация токена означает, что злоумышленник получит полный контроль над ботом, поэтому его следует хранить в переменных окружения, а не в коде.
Самый быстрый способ проверить, что токен работает, — отправить GET-запрос на эндпоинт /me. Ответ придёт в виде JSON с именем бота, его числовым user_id и флагом is_bot: true. Если вместо этого вы видите 401 Unauthorized, токен неверный или был сгенерирован заново после предыдущего запроса.
Для тех, кто хочет поэкспериментировать без прохождения полной верификации, существует альтернативный путь прямо внутри мессенджера: найдите @MasterBot через поиск, отправьте команду /create и пройдите пошаговый сценарий. В итоге получите тестового бота без написания кода — это удобно для быстрого прототипирования интерфейса.
SDK, библиотеки и выбор технологии
МАКС предоставляет официальные клиентские библиотеки для TypeScript и Go, опубликованные в официальной GitHub-организации max-messenger. Сообщество разработчиков дополнило экосистему клиентами для Python и PHP. Все они берут на себя рутину: сериализацию запросов, автоматический парсинг вебхуков, маршрутизацию событий по типам и управление состоянием соединения. Без библиотеки каждый эндпоинт придётся вызывать вручную через fetch или axios, что быстро превращается в объёмный шаблонный код.
Выбор технологического стека зависит от задачи и опыта команды. Для небольших ботов с простой логикой Python с библиотекой maxapi — оптимальный выбор: минимум синтаксического шума, богатая экосистема ML-инструментов на случай, если захочется добавить NLP. TypeScript подходит для более сложных проектов, где важна типобезопасность и нужно переиспользовать логику между ботом и веб-приложением. Go имеет смысл там, где критична производительность и минимальное потребление памяти — например, в ботах, обслуживающих сотни тысяч пользователей одновременно.
Язык | Библиотека | Тип поддержки |
|---|---|---|
TypeScript | @maxhub/max-bot-api | Официальная |
Go | max-bot-api-client-go | Официальная |
Python | maxapi | Сообщество |
PHP | max-bot-api-client-php | Сообщество |
Режимы получения обновлений
Прежде чем написать первую строку бизнес-логики, нужно определиться с тем, как бот будет узнавать о новых событиях. MAX поддерживает два режима — Long Polling и Webhook — и использовать их одновременно невозможно: включение одного автоматически отключает второй.
Long Polling работает по принципу «бот спрашивает сам»: приложение периодически отправляет GET-запрос на /updates и получает в ответ список накопившихся событий. Это удобно для локальной разработки: не нужен публичный домен, не нужен HTTPS, достаточно запустить скрипт на ноутбуке. Однако в продакшене Long Polling создаёт постоянную нагрузку на канал связи и увеличивает задержку между событием и реакцией бота — особенно в периоды пиковой нагрузки, когда очередь обновлений переполняется.
Webhook — противоположный подход: бот пассивно ожидает, пока платформа сама не пришлёт событие на зарегистрированный HTTPS-адрес. Регистрация выполняется одним POST-запросом на /subscriptions с телом: url вашего вебхука. После этого каждое событие — новое сообщение, нажатие кнопки, вступление пользователя в чат — будет мгновенно приходить на ваш сервер. Для продакшена это единственный правильный выбор. Важно: сервер должен отвечать HTTP 200 в течение нескольких секунд, иначе платформа будет повторять доставку, что может привести к дублированию обработки событий.
Структура запросов и форматирование сообщений
Каждый запрос к API MAX имеет единую структуру: метод HTTP, путь эндпоинта, заголовок Authorization с токеном и опциональное тело в JSON. Для отправки сообщения используется POST на /messages с полями chat_id — идентификатор чата или пользователя — и text — текст сообщения. Дополнительно можно указать параметр format со значением markdown или html, чтобы использовать разметку прямо в тексте.
MAX поддерживает жирный шрифт, курсив, зачёркивание, подчёркивание, моноширинный код и гиперссылки. Оба формата — Markdown и HTML — работают одинаково надёжно, выбор остаётся за командой. Редактирование сообщений доступно только в течение первых 24 часов после отправки, что нужно учитывать в архитектуре: если сценарий предполагает обновление статуса через несколько дней, придётся отправлять новое сообщение, а не редактировать старое.
Клавиатуры, кнопки и интерактивность
Интерактивность бота строится на inline-клавиатурах. МАКС поддерживает до 210 кнопок в одном сообщении — 30 рядов по 7 кнопок — что значительно больше, чем позволяет Telegram с его лимитом в 100 кнопок. Клавиатура передаётся как элемент массива attachments в теле запроса отправки сообщения с типом inline_keyboard. Каждая кнопка — объект с полями type, text и дополнительными параметрами в зависимости от типа.
Кнопка request_contact заслуживает отдельного внимания: в отличие от Telegram, MAX реализует верификацию подлинности переданного номера через HMAC-SHA256 подпись. Это означает, что вы можете быть уверены — пользователь передал именно свой номер, а не произвольную строку. Для B2C-ботов, где телефон является ключом в CRM, это серьёзное преимущество перед конкурентами.
Типы кнопок отражают разнообразие пользовательских сценариев:
callback — отправляет событие message_callback на ваш сервер с произвольным payload до 255 символов; основной тип для навигации по меню
link — открывает внешнюю ссылку до 2048 символов; подходит для перехода на сайт или в каталог
message — отправляет заданный текст от имени пользователя; удобно для выбора из фиксированных вариантов
request_contact — запрашивает у пользователя номер телефона с верификацией через HMAC-SHA256
request_geo_location — запрашивает текущую геолокацию пользователя
open_app — открывает мини-приложение MAX внутри мессенджера
clipboard — копирует текст в буфер обмена; идеально для промокодов и реквизитов
Работа с файлами и диплинки
MAX поддерживает загрузку файлов размером до 4 ГБ с механизмом resumable upload — это один из самых весомых технических аргументов в пользу платформы по сравнению с Telegram, где лимит составляет 50 МБ. Resumable upload разбивает большой файл на чанки и позволяет продолжить загрузку с места обрыва, не начиная сначала — критически важно при нестабильном соединении.
Механика вложений в МАКС принципиально отличается от telegram-овского file_id. В Telegram вы один раз загружаете файл, получаете идентификатор и переиспользуете его в других запросах. В MAX каждое вложение описывается через объект с типом и URL или данными файла. Это означает, что готовый код Telegram-бота, работающий с медиа, нельзя просто адаптировать — его нужно переписывать. Для отправки изображения нужно сначала загрузить файл через эндпоинт /uploads, получить token загруженного файла, а затем передать его в поле attachments при отправке сообщения.
Диплинки — механизм, позволяющий открывать бота с передачей произвольного параметра прямо в ссылке. Формат: https://max.ru/имяБота?start=payload, где payload может содержать до 128 символов. Когда пользователь переходит по такой ссылке, бот получает событие bot_started с переданным значением. На практике диплинки используются в трёх основных сценариях: реферальные программы, отслеживание источников трафика и глубокая персонализация.
Частые ошибки и архитектурные рекомендации
Самая распространённая ошибка при разработке — хранение токена прямо в коде. Когда репозиторий с таким кодом случайно становится публичным, злоумышленники получают полный контроль над ботом в течение нескольких минут. Всегда используйте переменные окружения или файл .env, который добавлен в .gitignore. Это элементарное правило безопасности, которое нарушает удивительно большое количество команд.
Вторая типичная проблема — отсутствие обработки дублирующихся событий. Если вебхук-сервер не ответил вовремя, MAX повторит запрос. Без механизма идемпотентности бот выполнит одно действие дважды — дважды начислит бонусы, дважды создаст заявку в CRM. Храните update_id последних обработанных событий в быстром хранилище и проверяйте каждое входящее событие перед обработкой.
Архитектурно лучшая практика в 2026 году — разделять транспортный слой и бизнес-логику с первого дня разработки. Такой подход позволяет добавить VK или вернуть Telegram как новый транспорт, не переписывая ни строчки сценариев. Основные принципы правильной архитектуры:
Транспортный слой занимается только коммуникацией с API платформы и нормализует события в единый формат
Бизнес-логика не знает, с какого мессенджера пришло событие — она работает с абстрактными объектами
Состояния диалогов хранятся в отдельном слое — Redis или PostgreSQL — а не в памяти процесса
Каждое входящее событие логируется с сырым телом до обработки, чтобы воспроизвести баг по реальным данным
