Как перенести бота из Telegram в MAX: пошаговый план

Как перенести бота из Telegram в MAX: пошаговый план для разработчика

Разбираемся, что меняется при переносе чат-бота из Telegram в мессенджер MAX, как сопоставить сущности двух API и как не поддерживать потом два разных проекта.

Сценарий, с которым сейчас приходят многие компании: бот давно работает в Telegram, аудитория частично переезжает в MAX, и бот нужен там тоже. Первая мысль — «скопируем код и поменяем адрес API». Не выйдет: у MAX свой Bot API, своя модель регистрации, свои события и лимиты. Хорошая новость — концептуально платформы похожи, и перенос можно сделать предсказуемым. В статье: чек-лист подготовки, таблица соответствия сущностей Telegram и MAX, два пути переноса и типичные ошибки.

Шаг 0. Проверьте, можете ли вы вообще завести бота в MAX

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

Что взять с собой из Telegram-бота

• Карта сценариев. Список команд, кнопок и шагов диалога — лучше в виде схемы. Это главный артефакт переноса: код меняется, сценарий — нет.
• Тексты. Все ответы бота. Проверьте разметку: если бот использует Markdown или HTML Telegram, в MAX её нужно будет проверить отдельно.
• Данные пользователей. Идентификаторы пользователей в Telegram и MAX разные — связать аккаунты автоматически нельзя. Если бот хранит историю, баллы или подписки, продумайте привязку: например, через код из личного кабинета или номер телефона.
• Медиа. file_id из Telegram в MAX не работает: изображения и файлы нужно будет загрузить в MAX заново и сохранить уже его идентификаторы.

Соответствие сущностей Telegram и MAX

Из таблицы видно главное: почти у каждой сущности Telegram есть аналог в MAX, но с другим именем и форматом. Поэтому перенос — это не правка адреса API, а переписывание транспортного слоя: приёма событий, отправки сообщений и работы с кнопками.

Путь 1: переписать транспорт вручную

Если бот написан на Telegraf или grammY, бизнес-логика обычно перемешана с Telegram-сущностями: ctx.reply, ctx.callbackQuery, Markup.inlineKeyboard. Порядок работы такой:

1. Вынесите логику в отдельные функции, которые принимают текст пользователя и возвращают «что ответить»: текст, кнопки, картинку. Без ctx внутри.
2. Напишите для MAX тонкий слой: HTTP-обработчик вебхука с проверкой секретного заголовка, разбор событий bot_started, message_created, message_callback, отправку сообщений с очередью под лимит 500 мс.
3. Переведите Telegram-обработчики на те же функции логики — иначе вы получите два бота, которые разъедутся после первой же доработки.

Путь рабочий, но по сути вы пишете собственный мини-фреймворк и дальше поддерживаете его сами: каждое изменение API любой из платформ — ваша задача.

Путь 2: мультиплатформенный фреймворк

Второй вариант — сразу вынести логику в мультиплатформенный фреймворк umbot, где транспорт каждой платформы уже написан. Логика описывается один раз, а Telegram и MAX подключаются адаптерами:

import { Bot, BotController, FALLBACK_COMMAND } from 'umbot';
import { TelegramAdapter, MaxAdapter, MongoAdapter } from 'umbot/plugins';

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

const bot = new Bot()
    .use(new TelegramAdapter(process.env.TELEGRAM_TOKEN))
    .use(new MaxAdapter(process.env.MAX_TOKEN, { secret: process.env.MAX_WEBHOOK_SECRET }))
    .use(new MongoAdapter({ host: process.env.DB_HOST ?? 'mongodb://localhost:27017', database: 'bot' }));

const greet = (bc: BotController) => {
    bc.text = 'Здравствуйте! Выберите раздел:';
    bc.buttons.addBtn('Каталог').addBtn('Доставка').addBtn('Оператор');
};

// «Начать» в MAX приходит отдельным событием
bot.addEvent('start', greet);
// /start в Telegram — обычное сообщение (слот срабатывает и на «/start параметр»)
bot.addCommand('start', ['/start'], (_, bc) => greet(bc));

bot.addCommand('delivery', ['доставка', 'сроки доставки'], (_, bc) => {
    bc.text = 'Доставляем по городу за 1–2 дня. Для расчёта напишите адрес.';
    bc.thisIntentName = 'ask_address';
});

bot.addStep('ask_address', (bc) => {
    bc.userData.address = bc.userCommand;
    bc.text = 'Спасибо! Менеджер рассчитает доставку и напишет вам.';
    bc.thisIntentName = null;
});

bot.addCommand(FALLBACK_COMMAND, [], (_, bc) => {
    bc.text = 'Не понял запрос. Выберите раздел кнопками ниже.';
    bc.buttons.addBtn('Каталог').addBtn('Оператор');
});

bot.start('0.0.0.0', 3000);

Одно приложение принимает вебхуки обеих платформ и само определяет, откуда пришёл запрос. Адаптер MAX проверяет секретный заголовок, соблюдает лимит отправки через очередь, переводит кнопки в формат клавиатуры MAX и обрезает их по лимитам. Обратите внимание на начало диалога: в MAX это отдельное событие bot_started (обработчик addEvent('start'), параметр deep-link — в bc.payload), а в Telegram /start — обычное текстовое сообщение, поэтому для него зарегистрирована команда. Оба пути ведут в одну функцию приветствия.

Обратите внимание на MongoAdapter: ни Telegram, ни MAX не хранят состояние диалога за вас. Без базы данных шаг «введите адрес» переживёт только до перезапуска процесса.

Подключение вебхука MAX

Вебхук в MAX включается запросом POST /subscriptions с адресом сервера и секретом. Адрес — только HTTPS на стандартном порту 443; секрет — от 5 до 256 символов из латиницы, цифр, _ и -:

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"}'

Если Telegram-бот уже работает через вебхук на вашем сервере, MAX можно направить на тот же адрес: разделять эндпоинты не обязательно.

Как проверить перенос до запуска

• Пройдите весь сценарий в обоих мессенджерах, включая «Начать», нераспознанные фразы и выход из каждого шага.
• Проверьте сообщения, которые бот отправляет пачкой: в MAX без очереди часть из них упрётся в лимит 500 мс на диалог.
• Проверьте длинные тексты: лимит MAX (4000 символов) чуть меньше, чем в Telegram.
• Прогоните логику автотестами без сети — в umbot для этого есть BotTest, см. статью про тестирование без публикации.

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

• Копия вместо общего кода. Два независимых бота расходятся уже через месяц: доработали сценарий в Telegram — забыли в MAX.
• Молчание на «Начать». В Telegram приветствие висит на /start, а в MAX это отдельное событие. Не обработали — первое касание пользователя остаётся без ответа.
• Перенос file_id. Идентификаторы файлов Telegram в MAX не действуют — медиа нужно загрузить заново.
• Вебхук без секрета. Без проверки заголовка любой, кто узнал адрес, сможет писать боту от имени любого пользователя.
• Ожидание автоматической миграции пользователей. Аудиторию придётся пригласить: ссылка на бота в MAX в самом Telegram-боте, на сайте и в рассылке.

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

Можно ли держать бота одновременно в Telegram и MAX? Да, и это самый разумный вариант на период переезда аудитории. Главное — одна логика на оба мессенджера.

Сколько времени занимает перенос? Зависит не от числа команд, а от того, насколько логика отделена от Telegram-кода. Если отделена — дни; если перемешана — сопоставимо с разработкой бота заново.

Нужно ли переписывать бота, если он на Python? Для переноса на MAX — нет: MAX доступен из любого языка через HTTP API. Но если планируется развитие на нескольких платформах, стоит оценить переход на фреймворк, где они уже поддержаны.

Куда дальше

• Бот для мессенджера MAX: создание на Node.js — регистрация, особенности API и первый бот.
• Интеграция с платформами в umbot — настройки адаптеров Telegram и MAX.
• Перенос и разработка ботов под ключ — если переезд нужен, а заниматься им некому.