Telemax

Двусторонний мост между мессенджером MAX и Telegram: один номер MAX превращается в Telegram-группу с форум-темами (по одной на каждый MAX-чат), и переписка идёт в обе стороны как в едином окне.

⚠️ Неофициальный проект. Не связан с MAX и Telegram, работает поверх вашего собственного номера/аккаунта на свой страх и риск — см. «Отказ от ответственности».

Возможности

• Текстовые сообщения, фото, файлы, голосовые, видео и видео-кружки (обе стороны)
• Стикеры — статичные и анимированные (обе стороны)
• Геолокация и контакты (обе стороны)
• Опросы: создание и голосование в обе стороны, актуальный счёт по команде /poll
• Удаление сообщений в обе стороны
• Пересылка сообщений — обычным drag-forward в Telegram, с автоматической пометкой источника
• Управление MAX-группами прямо из Telegram: создание, приглашение/удаление участников, переименование, описание, выход, удаление
• Уведомления о звонках (входящий/завершённый/пропущенный) — только текстом, без передачи аудио
• Веб-панель мониторинга: статус подключения, живые метрики, экран первой авторизации
• /reboot — полный сброс и пересинхронизация Telegram-стороны без повторной авторизации в MAX
• /kill — аварийный сброс: то же самое + разлогинивание MAX-сессии и полное стирание сохранённых данных
• /version — проверка обновлений и обновление по кнопке прямо из Telegram (см. «Обновление»)
• /apikey — напомнить ключ веб-панели, если потерялся
• Аватарка группы и цвет иконки каждой темы форума выставляются автоматически

Полный список команд бота — /help прямо в боте после запуска.

Требования

• Docker + Docker Compose
• Telegram-бот (токен из @BotFather) и Telegram-группа с включёнными темами (forum topics), куда бот добавлен администратором с правом «Управление темами» (Manage Topics) — без него бот не сможет создавать темы под MAX-чаты
• Номер MAX, на который будет авторизован мост

Быстрый старт

На чистом Ubuntu/Debian-сервере (по SSH, от root) — одна команда:

curl -fsSL https://raw.githubusercontent.com/Trollobot/Telemax/main/install.sh | bash

Она сама обновит систему, поставит git, Docker и jq (если их ещё нет), склонирует проект в /opt/telemax и запустит интерактивную настройку. Спросит токен Telegram-бота (создаётся через @BotFather) — id группы искать не придётся: добавьте бота в свою группу (с включёнными темами) администратором, отправьте туда любое сообщение, и скрипт сам определит нужный id. Секретные ключи сгенерирует сама, соберёт образ и запустит контейнер. Первая сборка дольше обычного (внутри образа headless-браузер для рендера анимированных стикеров) — это нормально, обычно несколько минут. В конце спросит номер телефона MAX и код из SMS прямо в консоли — переключаться в браузер для первого запуска не нужно (подробнее — «Первая авторизация»). Безопасно запускать повторно.

Если Docker и git уже стоят (или разворачиваете не с нуля) — то же самое, но без системной части:

git clone https://github.com/Trollobot/Telemax.git
cd Telemax
./setup.sh

Совсем руками, без интерактивных скриптов:

cp .env.example .env
# впишите TELEGRAM_BOT_TOKEN и TARGET_TELEGRAM_GROUP, остальное сгенерируйте:
# openssl rand -hex 24   -> API_KEY
# openssl rand -hex 32   -> MAX_SESSION_KEY
docker compose up -d --build

Первая авторизация

setup.sh сам спрашивает номер телефона MAX и код из SMS в конце установки — прямо в консоли, без веб-панели. После успешной авторизации сессия сохраняется зашифрованной в .data/ — повторной авторизации при перезапуске контейнера не требуется.

Веб-панель (https://<сервер>:порт, ключ — API_KEY из .env или команда /apikey в боте) нужна не для первого запуска, а для всего, что происходит позже: повторная авторизация после /kill, смена номера, живые метрики и логи. Если консольную авторизацию при установке пропустили (или она не удалась) — то же самое можно сделать там же.

Безопасность

Бот отвечает только внутри той Telegram-группы, что указана в TARGET_TELEGRAM_GROUP — любое сообщение или нажатие кнопки из другого чата (личка боту, добавление в чужую группу и т.п.) игнорируется. Это единственная граница доверия: у кого есть доступ к группе, у того есть доступ ко всем командам бота, включая /reboot, /kill и /apikey — относитесь к составу участников группы соответственно.

Веб-панель работает по HTTPS с самоподписанным сертификатом (генерируется при первом старте, лежит в .data/tls) — ключ панели, SMS-код и пароль MAX не ходят по сети открытым текстом. Браузер при первом входе один раз предупредит о неизвестном издателе — это ожидаемо, нажмите «Дополнительно» → «Перейти на сайт». Если панель стоит за вашим собственным reverse proxy с настоящим TLS — поставьте PANEL_TLS=off в .env.

Сертификаты российского государственного УЦ (нужны только потому, что через них выпущен TLS-сертификат самого MAX) доверяются только соединениям с серверами MAX — запросы к Telegram, GitHub и всему остальному проверяются исключительно по стандартному набору корневых сертификатов Mozilla (подробнее — certs/README.md).

Обслуживание

docker compose logs -f      # логи
docker compose restart      # перезапуск
docker compose down         # остановка

Все состояние (сессия MAX, привязка чатов к темам) лежит в ./data на хосте — бэкап этой папки достаточен для переноса на другой сервер.

Обновление

Раз в сутки (в случайное время) бот сам проверяет, есть ли на GitHub новые коммиты в main, и если да — присылает в группу сообщение с кнопками «Обновить» / «Позже». То же самое можно спросить в любой момент командой /version.

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

• Кнопка «Обновить» просто оставляет файл-маркер в ./data.
• На хосте (не в контейнере) параллельно работает systemd-таймер telemax-updater, который ставит setup.sh — раз в минуту проверяет этот маркер, и если он есть, запускает update.sh (git pull → пересборка образа → docker compose up -d).
• Таймер добавлен в автозапуск (systemctl enable), то есть переживает перезагрузку сервера.
• update.sh пишет в группу на каждом шаге: сразу — что начал, при ошибке (git pull/сборка/рестарт/контейнер не поднялся) — что именно сломалось и что мост остался на прежней версии. После успешного перезапуска бот сам напишет, до какой версии обновился.

Проверить/поуправлять им можно как обычным systemd-юнитом:

systemctl status telemax-updater.timer   # включён ли, когда сработает в следующий раз
systemctl disable --now telemax-updater.timer   # выключить совсем — обновляться придётся вручную: ./update.sh

Отказ от ответственности

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

Переписка, которую бот пересылает, временно оседает на вашем собственном сервере: в логах контейнера, в персистентном хранилище (./data) и в истории самой Telegram-группы. Проект не несёт ответственности за сохранность, утечку или неправомерное использование этих данных — обеспечение их безопасности (доступ к серверу, шифрование диска, ротация логов и т.д.) целиком на вас.

Обратная связь

Нашли баг — заводите Issue. Есть идея, вопрос или просто хотите поделиться впечатлениями — там же есть Discussions.

Поддержать проект

• Рублями: pay.cloudtips.ru/p/3c71b5e8
• GRAM (TON): UQALpK2PKI90-XpupOM8sRJGdwrFMsPcwQZPR0k180umXBcA

Разработка

npm install
npm run dev      # сервер + Vite dev middleware на http://localhost:3000
npm run lint      # проверка типов (бэкенд и фронтенд отдельно)
npm test          # vitest