В связи с тем, что Павел Дуров теперь террорист, Telegram скоро признают экстремистской сетью, что окончательно выведет бизнес в черную зону. Несмотря на то, что мы видим, как до сих пор всё прекрасно работает в соцсети с картинками, важно перестраховаться. Поэтому сейчас, чтобы «обелиться», многие бизнесы и эксперты переезжают или будут переезжать в другие соцсети, в том числе, в тот, который ловит даже на парковке.

Если вам кажется, что для перевода бота с Telegram на МАХ достаточно пары кликов: получить токен, поменять адрес API и подключить прежние обработчики, то, к сожалению, все не совсем так. Обычно это намного сложнее, ведь у платформ отличаются события, кнопки, медиа, работа с мини‑приложениями и идентификаторами.

А если вам не повезло, и в проекте намешаны бизнес‑логика и код конкретной платформы, то, скорее всего, надо будет написать практически нового бота.

MAX Bot API vs Telegram Bot API

Обе платформы работают через HTTP API, принимают обновления и позволяют отправлять сообщения, файлы и кнопки. На этом сходство в принципе заканчивается: запросы, события и ответы устроены по‑разному.

Как только мы начинаем углубляться, то различия заметны уже при настройке доставки обновлений. Telegram и MAX по‑разному регистрируют вебхуки, авторизуют запросы и передают данные. Объекты update, message, sender и callback‑события нельзя подставить друг вместо друга без преобразования.

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

Разберемся на примере

Возьмем оформление заказа. В Telegram обработчик получает chat.id, читает callback_data из inline‑кнопки, редактирует исходное сообщение и может открыть Web App.

В MAX придется отдельно разобрать:

• где лежат идентификаторы пользователя и чата;

• как выглядит входящее событие;

• как передается действие кнопки;

• как собираются клавиатуры;

• как загружаются и отправляются файлы;

• как запускается мини‑приложение;

• какие варианты редактирования сообщений доступны.

Как видно, токен и URL здесь — это капля в море).

Общая бизнес‑логика

Мне кажется, один из самых практичных вариантов — это выделить адаптер для каждой платформы. Он будет принимать нативное событие и превращать его во внутреннюю команду приложения:

• идентификатор пользователя;

• идентификатор чата;

• текст или команду;

• действие кнопки;

• вложения;

• данные о платформе;

• служебные поля события.

Домен работает с этой общей моделью. А когда нужно ответить пользователю, результат передается обратно в TelegramAdapter или MaxAdapter, где уже собирается запрос конкретного API.

При этом в такой схеме остаются общими база данных, сценарии заказа, регистрации, оплаты и поддержки. Отдельно живут шлюзы Telegram и MAX, а также реализация клавиатур, медиа и мини‑приложений.

Важно, что идентификаторы пользователей нужно хранить раздельно, ведь у одного человека разные Telegram ID и MAX ID. А следовательно, состояние диалога, права доступа и даже набор доступных функций тоже могут различаться.

Под это обычно заводят внутреннего пользователя и таблицу привязок:

users - id - created_at user_platform_accounts - user_id - platform - platform_user_id - username - metadata

Вебхуки и получение обновлений

Для Telegram и MAX нужны отдельные API‑клиенты и отдельная конфигурация вебхуков. Можно переиспользовать интерфейсы приложения, логирование и общую обработку ошибок. А сами запросы к API придется писать с учетом правил каждой платформы.

Тут тоже есть целый список интеграций, которые стоит проверить:

• как регистрируется и удаляется webhook;

• какие требования предъявляются к URL;

• как проходит авторизация;

• как устроен входящий JSON;

• каким ответом подтверждается доставка;

• когда платформа повторяет отправку события;

• гарантируется ли порядок событий;

• какие действуют таймауты;

• что происходит при недоступности сервера.

Важно, что обработчики стоит делать идемпотентными, то есть повторно доставленное событие не должно создать второй заказ, списать деньги еще раз или сбросить состояние диалога.

Клавиатуры и кнопки в MAX и Telegram

По моему опыту, кнопки удобнее сначала описывать во внутреннем формате:

Button - text - action - url - callback - app_launch

Дальше адаптер выбирает тип кнопки, доступный в Telegram или MAX.

Telegram поддерживает inline‑кнопки, callback‑запросы, URL‑кнопки, reply‑клавиатуры и Web Apps. В MAX часть этих сценариев устроена иначе, из‑за чего понадобится отдельная схема кнопок и обработчиков событий.

Для функций без прямого аналога заранее подготовьте запасной маршрут: ссылку на сайт, текстовую команду, дополнительный вопрос в чате, экран мини‑приложения или пункт меню.

Медиа и ограничения MAX Bot API

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

Особое внимание стоит уделить нескольким вопросам:

• какой максимальный размер файла;

• какие типы вложений принимает API;

• можно ли повторно использовать загруженный файл;

• когда истекает срок действия идентификатора файла;

• поддерживаются ли альбомы;

• как скачивать и хранить полученные файлы.

Привычный для Telegram file_id работает только внутри Telegram. MAX его, к сожалению, не распознает. Поэтому, если один файл нужен пользователям обеих платформ, лучше хранить оригинал в собственном хранилище, либо загружать его отдельно в каждый сервис.

Мини‑приложения Telegram и MAX

У мини‑приложений Telegram и MAX разные SDK, способы авторизации и жизненный цикл. Общий фронтенд часто удается сохранить, особенно если бизнес‑интерфейс живет в обычном веб‑приложении, а вот платформенный код лучше вынести отдельно.

Также проверки требуют авторизация, пользовательский контекст, подпись стартовых данных, параметры запуска, тема, закрытие окна, обмен данными с ботом и возврат в чат.

Функции Telegram без аналога в MAX

На мой взгляд, просто убрать функции Telegram, которых нет в MAX, и надеяться, что пользователи этого не заметят, затея так себе.

Для таких функций нужна матрица решений, которую я для себя вывел:

Дело в том, что проверка должна идти в обе стороны, так как у MAX тоже могут появиться возможности, которых еще нет в текущем Telegram‑боте. Документацию, лимиты и правила публикации лучше сверять перед проектированием и перед релизом: API стремительно развивается, а старые предположения быстро устаревают.

Чек‑лист миграции Telegram‑бота на MAX

Подведу небольшой итог тому, что я написал выше, чтобы было проще

1. Получить доступ организации и токен MAX.

2. Проверить требования к публикации приложения.

3. Выписать все функции существующего Telegram‑бота.

4. Собрать матрицу совместимости Telegram и MAX.

5. Настроить авторизацию и API‑клиент для MAX.

6. Подключить отдельный транспорт для webhook или long polling.

7. Привести сообщения, команды, callback‑события и вложения к общей модели.

8. Сопоставить кнопки, медиа, команды и Mini Apps.

9. Разделить Telegram ID и MAX ID в базе.

10. Вынести хранение файлов за пределы конкретной платформы.

11. Проверить лимиты, ретраи, таймауты и идемпотентность.

12. Подготовить запасные сценарии для отсутствующих функций.

13. Добавить SDK‑мосты для мини‑приложений.

14. Настроить мониторинг ошибок отдельно для Telegram и MAX.

15. Прогнать основные сценарии на реальных клиентах обеих платформ.

А с чего начать разработку бота для MAX?

Как обычно, надо оценить ситуацию «в целом». Выпишите все, что делает бот: команды, сообщения, кнопки, файлы, авторизацию, платежи, мини‑приложения, административные функции. Затем для каждой функции ответьте на несколько вопросов:

• есть ли она в Telegram;

• существует ли аналог в MAX;

• отличается ли формат вызова;

• нужен ли запасной сценарий;

• затрагивает ли различие доменную логику;

• потребуется ли отдельный интерфейс?

Такая работа помогает оценить проект до начала разработки. Я начал практиковать такой подход после того, как у меня несколько раз сначала казалось, будто работы на пару часов, а потом одно‑другое‑третье и времени потребовалось в два, а то и в три раза больше.

В целях упрощения себе жизни, общий доменный слой можно сохранить, а вот транспорт, события, клавиатуры, медиа, идентификаторы и мини‑приложения стоит вынести в адаптеры. В этом случае, кстати, Telegram и MAX как раз останутся частями одного продукта