Бот для мессенджера MAX: создание на typescript и Node.js

Бот для мессенджера MAX: создание на Node.js

Разбираемся, как создать бота в MAX: регистрация, вебхук, чем API отличается от Telegram и VK, и рабочий пример на Node.js.

MAX — мессенджер, который быстро набирает аудиторию в России, и для разработчиков ботов это редкая возможность: ниша ещё не занята. Бот, который в Telegram был одним из тысяч, в MAX может стать одним из первых в своей теме. Разберём, что нужно знать про создание бота для MAX на Node.js: где регистрировать бота, как подключить вебхук, чем API отличается от привычных мессенджеров и как не писать транспортную обвязку с нуля.

Что нужно, чтобы создать бота в MAX

• Верифицированный профиль организации или ИП на business.max.ru. Это главное отличие от Telegram: бота нельзя завести с личного аккаунта за минуту, как у @BotFather.
• Сервер с HTTPS — MAX доставляет события на вебхук, адрес должен быть доступен по HTTPS на стандартном порту 443.
• Node.js 20+ — для примера ниже.

Регистрация бота: пошагово

1. Откройте профиль организации на business.max.ru.
2. В разделе «Чат-боты» нажмите «Создать».
3. Заполните карточку бота: имя, описание, аватар — и сохраните. В настройках бота вы получите токен для работы с API.

Токен — это ключ ко всему боту: храните его в переменных окружения (.env), а не в коде и не в репозитории.

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

Что ещё важно учесть при разработке:

• Лимиты отправки. В один диалог — не чаще одного сообщения в 500 мс и не более 2 callback-ответов в секунду. Если бот отвечает несколькими сообщениями подряд, без очереди отправки часть из них получит ошибку 429.
• Вложения. До 12 вложений в сообщении, причём клавиатура тоже считается вложением. Файлы сначала загружаются на сервер MAX, а в сообщение передаётся полученный идентификатор.
• Начало диалога. Когда пользователь нажимает «Начать», приходит событие bot_started (в том числе с параметром payload из deep-link). На него обязательно нужно ответить приветствием — молчание на первое касание почти гарантированно означает потерянного пользователя.
• Групповые чаты. Если событие пришло из чата, в нём есть chat_id, и отвечать нужно в чат, а не в личный диалог.
• Нет хранилища состояния. Как и в Telegram, платформа не хранит состояние диалога за вас — нужна своя сессия или база данных.

Пример бота на Node.js с umbot

Проверку секретного заголовка, очередь отправки с учётом лимитов, загрузку вложений и разбор событий можно не писать руками: у мультиплатформенного фреймворка umbot есть готовый адаптер MAX. Пример по мотивам документации по платформам:

import { Bot, WELCOME_INTENT_NAME } from 'umbot';
import { MaxAdapter, FileAdapter } from 'umbot/plugins';

process.loadEnvFile(); // загружает .env в process.env (встроено в Node.js 20.12+)

const bot = new Bot();
// токен бота и секрет вебхука — из переменных окружения
bot.use(new MaxAdapter(process.env.MAX_TOKEN, { secret: process.env.MAX_WEBHOOK_SECRET }));
bot.use(new FileAdapter()); // хранение состояния пользователей (для продакшена — MongoDB)

// Пользователь нажал «Начать»
bot.addEvent('start', (bc) => {
    bc.text = 'Привет! Я бот в MAX. Чем помочь?';
    bc.buttons.addBtn('Меню').addBtn('Помощь');
});

bot.addCommand(WELCOME_INTENT_NAME, ['привет'], (_, bc) => {
    bc.text = 'Привет ещё раз!';
});

bot.addCommand('menu', ['меню'], (_, bc) => {
    bc.text = 'Выберите раздел:';
    bc.buttons.addBtn('Каталог').addBtn('Контакты');
});

bot.start('0.0.0.0', 3000);

Адаптер отклоняет запросы с неверным секретом (ответ 401), ставит исходящие сообщения в очередь с интервалом 500 мс на диалог и переводит кнопки и карточки в формат MAX, обрезая их по лимитам платформы. Параметр deep-link из события начала диалога доступен в bc.payload — удобно для рекламных ссылок вида «перейти в бота с меткой кампании».

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

Как запустить: по шагам

1. Создайте проект: npx umbot create my-max-bot, затем npm install. Файл для токенов — npx umbot add env.
2. Зарегистрируйте бота на business.max.ru и впишите токен в .env.
3. Придумайте секрет вебхука: от 5 до 256 символов, латиница, цифры, _ и -.
4. Соберите и запустите приложение (npm run build, npm start) на сервере с HTTPS — например, за nginx с сертификатом Let's Encrypt.
5. Подпишите бота на вебхук: отправьте запрос POST /subscriptions в API MAX с адресом сервера и секретом:

   curl -X POST "https://platform-api2.max.ru/subscriptions" \
     -H "Authorization: $MAX_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"url": "https://bot.example.ru/", "secret": "my_webhook_secret"}'

6. Найдите бота в MAX, нажмите «Начать» — и получите приветствие.

Типичные ошибки

• Вебхук не на 443 порту или без HTTPS. Подписка не будет создана — сервер должен быть доступен по HTTPS на стандартном порту.
• Секрет в подписке и в приложении не совпадает. Все события будут отклоняться с 401, и бот «молчит» без видимых причин. Сверьте значения.
• Нет ответа на «Начать». Если не обработать начало диалога, первое впечатление от бота — тишина.
• Несколько сообщений подряд без очереди. Лимит 500 мс на диалог приводит к ошибкам 429 — отправляйте через очередь или одним сообщением.
• Состояние в памяти процесса. После перезапуска сервера бот «забудет», на каком шаге был пользователь. Подключите БД.

Бот в MAX и Telegram одним кодом

Если у вас уже есть бот для Telegram или навык Алисы на том же фреймворке, MAX подключается к нему ещё одним адаптером bot.use(new MaxAdapter(...)): команды, кнопки и состояние остаются общими. Как это устроено — в статье одна кодовая база для Алисы, Маруси и Telegram.

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

Можно ли создать бота в MAX как физическое лицо? На момент написания — нет: для создания бота нужен верифицированный профиль организации или ИП.

Можно ли перенести бота из Telegram в MAX? Код на Telegram-библиотеках (Telegraf, grammY) напрямую не переносится — API разные. Если логика написана на мультиплатформенном фреймворке, перенос сводится к подключению адаптера.

Поддерживает ли MAX голосовые ответы? Да, бот может отправлять аудио. В umbot синтез речи для MAX работает через Yandex SpeechKit — нужен отдельный токен SpeechKit.

Куда дальше

• Интеграция с платформами в umbot — MAX, Telegram, VK, Viber и голосовые в одном приложении.
• Развёртывание на сервере — nginx, HTTPS, Docker.
• Услуга: разработка ботов под ключ — если нужен готовый бот для MAX, а не фреймворк.