Как перенести Telegram-бота в MAX: что меняется в коде и API

У меня есть по одному демо-боту на каждой платформе: кофейня «Зерно и Пар» с Mini App в Telegram и «Виртуальный рекрутер» в MAX. Оба написаны на Python, и на них хорошо видно, где API похожи и где расходятся. Факты ниже сверены с документацией MAX для разработчиков, спецификацией api-schema и Telegram Bot API.

Бот в MAX принадлежит организации

В Telegram бота создаёт любой аккаунт через BotFather за пару минут. В MAX порядок другой. Нужен профиль на платформе MAX для партнёров, верифицированный как юрлицо, ИП или самозанятый (резидент РФ). Потом вы заполняете карточку бота и ждёте модерацию: по документации до 48 часов в рабочие дни. Пока бот на модерации, пользователи его не найдут, так что регистрацию лучше начинать в первый же день работ.

Никнейм выбрать нельзя, он формируется сам: idИНН_bot для организаций и ИП, se…_bot для самозанятых. Красивое имя из Telegram в MAX не повторить, поэтому ссылки на сайте, в QR-кодах и подписях писем придётся заменить. Подробно про верификацию и модерацию я писал в статье «Бот в MAX для бизнеса: как подключить».

Подписчики сами не переедут. Идентификатор пользователя в Telegram и user_id в MAX никак не связаны, базу «скопировать» не получится. Рабочий способ связать аккаунты такой: Telegram-бот отправляет человеку ссылку вида https://max.ru/<ник_бота>?start=<код>, где код одноразовый и хранится у вас в базе. Человек открывает её, MAX-бот получает событие bot_started с этим кодом и находит запись клиента. Параметр start вмещает до 128 символов. Телефон или email туда открытым текстом не кладут: правила платформы разрешают только одноразовые токены или закодированные идентификаторы.

Какие методы чем заменить

Общая модель знакомая: HTTPS-запросы с JSON, события через вебхук или опрос. Отличаются адреса, имена и мелочи в параметрах.

Токен в MAX передаётся в заголовке Authorization, а базовый адрес теперь https://platform-api2.max.ru. Старый домен platform-api.max.ru документация просит заменить, а токен в параметрах запроса больше не принимается. Если вы находили в интернете пример с ?access_token= в адресе, он устарел.

Ещё одна деталь, на которой спотыкаются в Python: документация просит добавить корневой сертификат Минцифры в доверенные. В моём клиенте для MAX это сделано отдельным SSL-контекстом, куда к стандартному набору certifi подгружается файл Russian Trusted Root CA. Без него запросы могут падать с ошибкой проверки сертификата, хотя токен правильный.

Библиотеки из Telegram-мира (aiogram, python-telegram-bot) с MAX не работают. Официальные клиенты у MAX есть для JavaScript/TypeScript и Go, для остальных языков есть спецификация OpenAPI. Для Python я написал свой клиент на httpx: вместе с повторами запросов и загрузкой файлов вышло около 160 строк.

События: вебхук строже, чем в Telegram

Типы событий называются иначе. Обычное сообщение приходит как message_created, нажатие кнопки как message_callback, первый запуск как bot_started. Если человек остановил бота, придёт bot_stopped. Это удобно для рассылок: такого пользователя сразу помечаете в базе и больше ему не пишете. Добавление и удаление бота из чата приходят как bot_added и bot_removed.

Требования к вебхуку у MAX жёстче. Telegram принимает порты 443, 80, 88 и 8443 и умеет работать с самоподписанным сертификатом, если загрузить его при setWebhook. MAX принимает только HTTPS на 443-м порту с сертификатом доверенного центра или Минцифры, полной цепочкой и доменом, который совпадает с сертификатом. HTTP и самоподписанные сертификаты не поддерживаются.

Сервер должен ответить 200 за 30 секунд. Если доставка не удалась, MAX повторяет попытку до 10 раз с растущим интервалом: через 60 секунд, через 150, через 375 и дальше. Если за 8 часов не было ни одного успешного ответа, бот автоматически отписывается от вебхука. Сервер, который пролежал ночь, утром поднимется, но событий получать не будет. Поэтому при каждом старте бота стоит заново вызывать POST /subscriptions, а в мониторинг добавить проверку, что события действительно приходят.

Проверка подлинности запроса похожа на Telegram. Там секрет приходит в заголовке X-Telegram-Bot-Api-Secret-Token, здесь в X-Max-Bot-Api-Secret, если вы указали secret при подписке. Long Polling в MAX документация называет способом для разработки: он ограничен по скорости и сроку хранения событий. Одновременно с вебхуком он не работает.

Кнопки устроены по-другому

В Telegram две клавиатуры: inline-кнопки под сообщением и reply-клавиатура внизу экрана. Запрос телефона (request_contact) и геолокации там возможен только через reply-клавиатуру. В MAX нижней клавиатуры нет, есть одно вложение inline_keyboard, и запрос контакта или геолокации стали обычными типами кнопок под сообщением. Если ваш Telegram-бот держит постоянное меню внизу экрана, в MAX его придётся перенести в кнопки под сообщением или в команды.

Ограничения MAX: до 30 рядов, до 7 кнопок в ряду, а для кнопок link, open_app, request_contact и request_geo_location не больше 3 в ряду. В payload кнопки помещается до 1024 символов против 64 байт callback_data в Telegram. Короткие коды вида vac:12:apply всё равно удобнее: их легко разбирать и логировать.

Ответ на нажатие тоже удобнее. В Telegram обычно два вызова: answerCallbackQuery, чтобы убрать часики, и editMessageText, чтобы обновить экран. В MAX POST /answers принимает новое сообщение целиком и короткое уведомление, так что экран меняется одним запросом.

Разметка и длина текста

Telegram-разметку один в один перенести не выйдет. MarkdownV2 требует экранировать почти всю пунктуацию, а Markdown в MAX свой: ++подчёркнутый++, ^^выделенный^^, # заголовок. Проще всего перевести оба бота на HTML. MAX понимает <b>, <i>, <u>, <s>, <a>, <code>, <pre>, <blockquote>, а также <mark> и <h1>. Остальные теги он вырезает, поэтому <tg-spoiler> из Telegram просто исчезнет. Формат задаётся полем format: "html" в теле сообщения.

Лимит текста в MAX 4000 символов, в Telegram 4096. Если бот режет длинные ответы на куски, порог нужно поправить, иначе куски длиннее 4000 символов MAX не примет.

Файлы загружаются в два шага

В Telegram PDF уходит одним запросом sendDocument, а повторно его можно отправить по file_id. В MAX сначала вызываете POST /uploads?type=file, получаете адрес, загружаете туда файл и получаете токен. Потом отправляете сообщение с вложением {"type": "file", "payload": {"token": "..."}}. file_id из Telegram в MAX не действуют, все файлы придётся загрузить заново.

Сразу после загрузки отправка иногда возвращает ошибку attachment.not.ready: файл ещё обрабатывается. В моём клиенте на этот код ответа стоит повтор с паузой, которая растёт с каждой попыткой. Без повтора бот, который присылает анкету или счёт в PDF, будет периодически «терять» документ. Как генерировать такие документы, разобрано в статье про автоматическую генерацию PDF, а пощупать генератор можно в демо.

Лимиты и рассылки

По FAQ Telegram в один чат лучше не слать чаще раза в секунду, в группу не больше 20 сообщений в минуту, а массовая рассылка упирается примерно в 30 сообщений в секунду. В MAX можно до двух сообщений в секунду в один чат, но общий лимит 30 запросов в секунду считается на все вызовы API сразу. Редактирования, ответы на кнопки и загрузка файлов идут в тот же счёт. Если рассылка займёт все 30 запросов, живые пользователи в это время будут ждать ответа. Рассылку лучше ставить в очередь с запасом и оставлять часть лимита на текущую работу бота. На ответ 429 клиент должен сделать паузу и повторить запрос.

Чего в MAX Bot API пока нет

Нет платежей. В Telegram есть sendInvoice и оплата в Telegram Stars, а в спецификации MAX Bot API на 4 ноября 2026 года методов оплаты нет. Рабочая схема такая: бот отправляет ссылку на платёжную страницу провайдера, провайдер присылает вебхук об оплате на ваш сервер, и только после него бот меняет статус заказа.

Inline-режима, когда бота вызывают через @ник в любом чате, в спецификации тоже нет.

Часть методов для групп изменилась в 2026 году. С июня не поддерживается GET /chats, а работа POST /chats/{chatId}/members ограничена с 9 сентября. Если ваш бот администрирует группы, сверьте каждый вызов с текущей документацией.

Мини-приложение переносится легче всего

Фронтенд Mini App переезжает почти целиком, потому что это обычная веб-страница. Меняется объект платформы: вместо window.Telegram.WebApp в MAX используется window.WebApp из MAX Bridge. Открывается приложение кнопкой open_app, параметр запуска передают через ?startapp=.

Проверка initData на сервере устроена так же, как в Telegram. Ключ получают через HMAC-SHA256 токена бота с ключом WebAppData, параметры сортируют и склеивают через перевод строки, подпись сравнивают с hash. Документация рекомендует считать данные устаревшими через час после auth_date. На проверку нужно брать строку initData, initDataUnsafe для этого не годится. Как устроена сама Mini App, я разбирал в статье про Telegram Mini App для кафе.

Порядок переноса

1. Сразу зарегистрировать организацию и бота в MAX, чтобы модерация шла параллельно с разработкой.
2. Вынести логику из обработчиков. Сценарий получает нейтральное событие (кто, какой текст, какая кнопка) и возвращает нейтральный ответ: текст, кнопки, файл.
3. Написать два адаптера, для Telegram и для MAX. Каждый переводит нейтральный ответ в вызовы своего API.
4. Хранить пользователей в одной базе с полем «платформа». Заявки, заказы и уведомления менеджеру общие.
5. Поднять вебхук на домене с нормальным сертификатом, настроить мониторинг событий и переподписку при старте.
6. Разослать в Telegram-боте сообщение со ссылкой на MAX и одноразовым кодом для тех, кто хочет перейти.

Объём работы зависит от второго пункта. Если логика уже отделена от aiogram, перенос сводится к адаптеру и тестам. Если message.answer вызывается в каждой функции, переписывать придётся всё, что касается интерфейса. Из чего складывается цена бота в MAX, я разобрал отдельно: «Сколько стоит разработать чат-бота для MAX».

Перед стартом. Откройте dev.max.ru в день начала работ. Только за 2026 год у MAX сменился домен API и способ передачи токена, а GET /chats перестал работать.

Если у вас есть Telegram-бот и нужна его версия для MAX, пришлите ссылку на бота или репозиторий. Посмотрю и скажу, какие части переедут без изменений, а какие придётся переписать.