Когда мы решили вывести нашего ИИ-ассистента Лиза Петровна за пределы Telegram, главным требованием было сохранить единый опыт: пользователь не должен замечать разницы между платформами. Бот в MAX должен был использовать ту же память диалога, тех же агентов и ту же логику ответов. В этой статье я расскажу, как мы реализовали подключение через Bot API, построили общий мост между мессенджерами и настроили диплинки для привлечения аудитории. Также поделюсь результатами первого запуска рекламы и типичными ошибками, которые лучше не повторять.

Архитектура общего моста: единый бэкенд для двух платформ

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

Такой подход позволяет легко добавлять новые каналы, не переписывая ядро. Важно продумать маппинг пользователей: если человек общается и в Telegram, и в MAX, мы хотим, чтобы он видел одну историю. Для этого при первом входе мы создаём внутренний профиль и связываем его с идентификаторами в каждой платформе. Связывание происходит либо через явную авторизацию (например, ввод кода из одного мессенджера в другом), либо через диплинк с токеном.

Работа с Bot API MAX: что учесть при интеграции

MAX предоставляет Bot API, аналогичный Telegram, но с рядом особенностей. Во-первых, документация менее обширна, поэтому пришлось экспериментировать. Во-вторых, некоторые методы имеют отличия в параметрах — например, отправка медиагрупп или работа с клавиатурами. Мы советуем сразу написать обёртку над API, которая будет скрывать эти различия и предоставлять единый интерфейс для отправки сообщений.

  • Авторизация бота: токен выдаётся при регистрации бота в MAX. Храните его в защищённом хранилище и не коммитьте в репозиторий.
  • Вебхуки: MAX поддерживает установку вебхука. Убедитесь, что ваш сервер отвечает быстро (таймаут обычно небольшой), иначе возможны повторные доставки.
  • Форматы сообщений: проверьте поддержку Markdown или HTML. В MAX, как и в Telegram, есть режимы разметки, но синтаксис может отличаться.
  • Лимиты: хотя явных ограничений меньше, чем в Telegram, стоит кэшировать часто запрашиваемые данные и не спамить запросами.

Отдельно стоит продумать обработку ошибок: если MAX временно недоступен, сообщение не должно теряться. Мы используем очередь с повторными попытками и логируем сбои для мониторинга.

Диплинки: как привлекать и связывать аудиторию

Диплинки (deep links) — мощный инструмент для маркетинга и аналитики. В MAX они работают аналогично Telegram: вы можете сформировать ссылку вида https://max.ru/your_bot?start=payload, где payload передаётся боту при первом запуске. Это позволяет отслеживать источник перехода, автоматически связывать аккаунты и выдавать персонализированные приветствия.

Мы использовали диплинки в рекламных кампаниях. Например, в объявлении для MAX указывали ссылку с меткой utm_source=max_ad, а для Telegram — с utm_source=tg_ad. При переходе бот сохранял метку в профиле пользователя и мог адаптировать первый ответ. Это дало понимание, какая платформа эффективнее.

Также диплинки помогли реализовать бесшовное связывание: если пользователь уже общался с ботом в Telegram, но пришёл в MAX по ссылке с токеном, мы автоматически подтягивали его историю. Для этого в payload передавался одноразовый токен, сгенерированный в личном кабинете.

Результаты запуска и типичные ошибки

После включения рекламы за период 2–5 ноября к нам пришли 416 человек: 311 в MAX и 126 в Telegram (один пользователь мог зайти в оба мессенджера, поэтому сумма больше общего числа). Неожиданно MAX показал более высокую конверсию, возможно, из-за меньшей конкуренции среди ботов. Однако мы столкнулись с рядом проблем.

  • Задержки в ответах MAX: из-за неоптимизированных запросов к API бот иногда отвечал дольше обычного. Решили кэшированием и асинхронной обработкой.
  • Несовпадение клавиатур: кнопки, отправленные в Telegram, не отображались в MAX из-за различий в форматах. Пришлось делать отдельные рендереры для каждой платформы.
  • Потеря контекста при связывании: если пользователь заходил в MAX без диплинка, система не могла найти его профиль в Telegram. Добавили возможность ручного ввода кода связывания.
  • Аналитика: сначала мы не разделяли метрики по платформам, что мешало оценить эффективность. Теперь каждый запрос логируется с указанием мессенджера и источника.

В целом интеграция прошла успешно, и мы планируем развивать присутствие в MAX. Главный совет: не пытайтесь сделать универсальный код «на все случаи» — лучше иметь чёткие адаптеры и следовать документации каждой платформы. И обязательно тестируйте сценарии с реальными пользователями на раннем этапе.