maxbridge

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

Сделано для себя. Если пригодится кому-то ещё — пользуйтесь.

   MAX (личный аккаунт)                    Telegram
   ─────────────────────                   ─────────────────────
   pymax, сессия по QR/СМС  ──входящие──►  топик «Мама»
                                           топик «Рабочий чат»
                            ◄──ответы────  топик «Сестра»
                                           (одна супергруппа с темами)

Один процесс держит оба клиента в одном событийном цикле: pymax для MAX и aiogram для Telegram-бота на официальном Bot API.

Возможности

• Личка и группы MAX, каждый чат — свой топик, с именем отправителя
• Ответы из Telegram уходят в нужный MAX-чат, на отправленном появляется ✅
• Вложения в обе стороны: фото, файлы, видео, голосовые, стикеры
• Догонка пропущенного: сообщения, пришедшие пока сервис лежал, добираются при старте
• /mute для шумных чатов, /status, /id
• Сессия MAX переживает перезапуски и перезагрузку сервера
• Автопереподключение, уведомление в Telegram, если мост упал
• Ежедневный бэкап привязок топиков
• Несколько независимых экземпляров на одном сервере (себе, жене, кому угодно)
• Секреты в .env, ничего в коде

Установка

Нужен Python 3.10 или новее. Всё остальное установщик сделает сам.

1. Подготовь Telegram

1. Создай бота. Напиши @BotFather: /newbot, придумай имя — он выдаст токен. Затем /setprivacy → выбери своего бота → Disable (иначе бот не увидит твои ответы).
2. Создай группу и добавь в неё этого бота.
3. В настройках группы включи «Темы» (Topics).
4. Сделай бота администратором с правом «Управление темами».
5. Напиши в группе любое сообщение — по нему установщик найдёт её сам.
6. Открой бота в личке и нажми «Запустить» — иначе он не сможет сообщать тебе о неполадках.

2. Запусти установщик

Linux (Ubuntu 22.04+ или Debian):

git clone https://github.com/maximdr86/maxbridge.git
cd maxbridge
sudo bash install.sh

Windows (10 или 11): скачай репозиторий кнопкой Code → Download ZIP, распакуй и запусти install.cmd. Нужны права администратора — без них Windows не даст создать задачу с автозапуском; установщик сам попросит их и откроет новое окно, достаточно подтвердить.

3. Ответь на вопросы

Установщик спросит имя экземпляра, токен бота и телефон MAX, найдёт группу сам и в конце покажет QR-код — отсканируй его приложением MAX (Настройки → Устройства → Подключить устройство).

Всё. Мост запустится и будет подниматься сам после перезагрузки.

Подробности, ручная установка и разбор частых проблем — в INSTALL.md для Linux и INSTALL-WINDOWS.md для Windows.

Как это устроено

Файл	Назначение
bridge.py	сам сервис: MAX-клиент и Telegram-бот в одном процессе
storage.py	SQLite: привязки топиков, заглушённые чаты, метки прочитанного
auth.py	одноразовый вход в MAX (QR или СМС)
install.sh / uninstall.sh	мастер установки и удаления, Linux
install.cmd / uninstall.cmd	то же для Windows (зовут install.py)
diag.py	диагностика: проверяет Telegram и MAX по отдельности
logout.py	корректный отзыв сессии MAX
alert.sh, backup.sh	уведомление о падении и бэкап привязок
maxbridge@.service	шаблонный systemd-юнит, по экземпляру на аккаунт
backup.py	копия привязок топиков, обе системы

Конфигурация

Всё в .env экземпляра, шаблон — .env.example.

Параметр	По умолчанию	Что делает
TG_BOT_TOKEN	—	токен бота от @BotFather
TG_GROUP_ID	—	ID супергруппы с включёнными «Темами»
TG_OWNER_ID	—	твой Telegram ID, только от него принимаются ответы
AUTH_MODE	sms	sms или qr — способ входа в MAX
ALLOW_SEND	true	разрешить отвечать из Telegram в MAX
MIRROR_OWN	false	дублировать свои сообщения, отправленные с телефона
MEDIA	true	пересылать вложения
MEDIA_MAX_MB	45	потолок размера вложения из MAX в Telegram
SERVICE_EVENTS	false	пересылать служебные события MAX
READ_ON_REACTION	true	отмечать прочитанным в MAX по реакции в Telegram
CATCHUP	true	догонять пропущенное при старте
CATCHUP_LIMIT	50	глубина окна догонки, сообщений на чат

Команды в группе

Команда	Что делает
/status	состояние моста
/id	chat_id, thread_id, твой user_id
/mute / /unmute	заглушить чат, в топике которого вызвана

Реакция на пересланное сообщение помечает его прочитанным в MAX. Bot API не сообщает боту о прочтении — таких событий для ботов нет, — поэтому реакция используется как осознанный сигнал «посмотрел». Тип реакции неважен. Отключается READ_ON_REACTION=false.

Ограничения

• 20 МБ — потолок на файл из Telegram в MAX. Ограничение Bot API, обойти на стороне бота нельзя.
• 50 МБ — потолок на загрузку в Telegram, поэтому из MAX берём 45.
• Оба снимаются, если поднять локальный Bot API server, но он кэширует у себя всё, что через него проходит, и требует отдельного диска.
• Опросы, контакты и записи о звонках приходят текстовой пометкой.

Предупреждение

Официальный Bot API мессенджера MAX доступен только верифицированным юрлицам, поэтому мост работает через неофициальный внутренний API — библиотеку PyMax.

Из этого следуют три вещи, о которых лучше знать заранее.

Во-первых, это нарушает условия использования MAX и теоретически может привести к блокировке аккаунта. Во-вторых, внутренний протокол меняется без предупреждения, и очередное обновление мессенджера может сломать мост — поэтому версия библиотеки в requirements.txt зафиксирована. В-третьих, файл сессии равносилен полному доступу к аккаунту: держи его на своём сервере, с правами 600, и не клади в git.

Мост рассчитан на свой собственный аккаунт. Настраивать его на чужой аккаунт без ведома владельца — это перехват переписки, а не автоматизация, и в России подпадает под ст. 138 УК РФ. Ставьте людям их собственные мосты.

Автор ответственности за блокировки, потерю данных и прочие последствия не несёт.

Благодарности

• PyMax — асинхронная обёртка над внутренним API MAX
• aiogram — Telegram Bot API

Лицензия

MIT, см. LICENSE.