Перенос Telegram-бота в MAX — не копирование одного токена и не автоматическая публикация. Бизнес-логику, базу данных и часть frontend-кода часто можно сохранить, но транспорт API, события, кнопки, авторизация Mini App, модерация и пользовательские идентификаторы требуют отдельной адаптации.
Самый устойчивый подход — общий backend с двумя платформенными адаптерами. Тогда продукт развивается один раз, а каждый мессенджер отвечает только за свой API и интерфейсные особенности.
При оценке переноса сверяйте реализацию с актуальным MAX API и MAX Bridge для Mini App: модели событий, авторизация и клиентские методы отличаются от Telegram.
Что обычно можно переиспользовать
- доменную бизнес-логику;
- базу товаров, услуг и контента;
- CRM- и 1С-интеграции;
- модели данных;
- очередь задач;
- AI-оркестрацию и базу знаний;
- административную панель;
- аналитику backend;
- большую часть frontend Mini App на React или другом web-стеке;
- тесты бизнес-правил.
Чем меньше исходный проект связан напрямую с Telegram API внутри всей кодовой базы, тем проще перенос.
Что нужно адаптировать
Регистрацию и владение
В MAX требуется верифицированный профиль организации, ИП или самозанятого. Бот создаётся на платформе для партнёров, получает автоматически сгенерированный ник и проходит модерацию.
API и события
Telegram Bot API и API MAX имеют разные endpoints, структуры обновлений, типы объектов и ограничения. Нужен отдельный слой преобразования входящих событий и исходящих сообщений.
Webhook
Для MAX production-обработчик работает по HTTPS и подписывается на события через /subscriptions. Токен передаётся в заголовке Authorization.
Кнопки и форматирование
Набор типов кнопок, payload, ограничения клавиатуры и поддерживаемое форматирование отличаются. Интерфейс сообщений нужно проверять отдельно, а не генерировать один и тот же JSON.
Mini App Bridge
Вместо Telegram Web Apps API используется MAX Bridge. Нужно заменить инициализацию, управление интерфейсом и получение стартовых параметров.
Валидацию пользователя
Алгоритм проверки initData отличается. Реализуйте официальный серверный механизм MAX и создавайте отдельную сессию.
Диплинки
В MAX Mini App открывается ссылкой вида:
https://max.ru/<botName>?startapp=<payload>Схему параметров можно сохранить на уровне продукта, но формат и ограничения нужно адаптировать.
Что нельзя перенести автоматически
Пользовательские идентификаторы разных платформ не совпадают. Нельзя считать Telegram user ID и MAX user ID одним человеком без дополнительной связи.
Также нельзя автоматически переносить:
- подписчиков канала;
- личные диалоги;
- историю сообщений;
- согласия на коммуникацию;
- платформенные права;
- ник бота;
- сохранённые кнопки и ссылки.
Если продукту нужен единый клиентский профиль, используйте подтверждённый телефон, корпоративную авторизацию или другой законный механизм связывания с согласия пользователя.
Рекомендуемая архитектура
Telegram Adapter ─┐
├─ Domain Core ─ CRM / 1С / AI / Database
MAX Adapter ──────┘Платформенный адаптер отвечает за:
- приём события;
- преобразование в общий внутренний формат;
- отправку сообщения;
- клавиатуру;
- загрузку файлов;
- диплинки;
- платформенные ошибки.
Domain Core не должен знать, как называется поле сообщения в конкретном API. Он работает с сущностями «пользователь», «заказ», «заявка», «статус» и «команда».
Пошаговый план переноса
1. Проведите инвентаризацию
Составьте список команд, событий, кнопок, Mini App-экранов, интеграций, фоновых задач и уведомлений. Отметьте, что связано с Telegram напрямую.
2. Выберите первый сценарий
Не переносите всё одновременно. Начните с функции, которая создаёт основную ценность: заявка, заказ, запись или поддержка.
3. Вынесите общую логику
Если обработчики Telegram одновременно содержат API-код, расчёты и работу с CRM, разделите их. Сначала сформируйте общий доменный слой.
4. Создайте профиль и бота MAX
Пройдите верификацию, создайте карточку и отправьте её на модерацию. После проверки получите токен.
5. Реализуйте MAX Adapter
Добавьте Webhook, преобразование событий, отправку сообщений, клавиатуры и обработку ошибок.
6. Адаптируйте Mini App
Подключите MAX Bridge, серверную валидацию initData, новую схему диплинков и платформенные элементы интерфейса.
7. Разделите идентификаторы
Храните платформу и user ID как составной ключ. Если нужен общий профиль, добавьте безопасную процедуру связывания.
8. Проведите сквозные тесты
Одинаковый бизнес-результат должен корректно создаваться из обоих каналов, но сообщения и интерфейс могут отличаться.
9. Запустите параллельный пилот
Не отключайте действующий Telegram-сценарий до проверки MAX. Направьте ограниченную аудиторию, сравните воронку и исправьте различия.
10. Настройте общий мониторинг
Разделяйте ошибки и метрики по платформам, но связывайте их с едиными бизнес-операциями.
Как адаптировать контент
Не переносите сообщения механически. Проверьте:
- длину текста;
- доступные форматы;
- количество кнопок;
- названия действий;
- переходы назад;
- поведение ссылки;
- отображение медиа;
- возможность поделиться контактом;
- работу в групповых чатах.
Структура диалога может остаться, но интерфейс должен выглядеть естественно для MAX.
Как сообщить пользователям о новом канале
Предлагайте конкретную пользу: доступ к записи, заказу, кабинету или поддержке. Не просите переходить только ради присутствия компании на новой платформе.
Используйте сайт, канал, email, офлайн-материалы и существующие коммуникации в рамках согласий. Для каждого источника создайте отдельный диплинк.
Как оценивать перенос
- доля функций, работающих на общем core;
- количество платформенных исключений;
- конверсия сценария по каждому мессенджеру;
- ошибки Webhook;
- время ответа;
- стоимость поддержки двух адаптеров;
- доля связанных клиентских профилей;
- качество заявок в CRM.
Частые ошибки
- Переписать весь backend без необходимости.
- Использовать Telegram user ID как идентификатор MAX.
- Перенести токен и секреты во frontend.
- Не адаптировать кнопки и форматирование.
- Дублировать бизнес-логику в двух кодовых базах.
- Отключить старый канал до пилота.
- Автоматически переносить согласия пользователей.
- Не разделять аналитику по платформам.
Частые вопросы
Можно ли использовать один backend для Telegram и MAX?
Да. Это рекомендуемая архитектура, если платформенная логика вынесена в отдельные адаптеры.
Нужно ли переписывать Mini App полностью?
Не всегда. Web-интерфейс и бизнес-компоненты можно переиспользовать, но Bridge, initData, диплинки и платформенные состояния необходимо адаптировать.
Можно ли перенести пользователей автоматически?
Нет, идентификаторы платформ различаются. Для единого профиля требуется дополнительная идентификация и законное связывание данных.
Можно ли сохранить одинаковый дизайн?
Основной бренд — да, но навигацию, кнопки и состояния лучше адаптировать к MAX UI и поведению webview.
Стоит ли поддерживать оба мессенджера?
Если аудитория распределена между ними, общий backend с адаптерами снижает стоимость. Решение следует принимать по использованию, конверсии и операционным затратам.