Telemax/README.md

Telemax

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

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

Возможности

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

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

Пульт управления

Команда /panel (и закреплённое в теме группы сообщение) открывает пульт с кнопками — меню прямо в Telegram-группе, без захода в веб-панель:

• 👤 Найти контакт — поиск MAX-контакта по номеру или нику; из карточки результата «Начать чат» в один тап создаёт диалог и его тему.
• 🚫 Управление чатами — заглушить (бан) или вернуть чат.
• 🌐 Веб-панель — ссылка для входа и API-ключ.
• ⚙️ Система — пауза MAX на время (10 мин / 1 час / 1 сутки / до ручного возобновления), обновление, пересинхронизация, список команд.

Пульт виден всем участникам группы, но кнопки/команды срабатывают только у администраторов.

Требования

• 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

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

⚠️ Не пропустите этот шаг. Запрос номера MAX и SMS-кода появляется в самом конце, уже после многоминутной сборки образа. Легко принять «Контейнер запущен» за финал и уйти — но без авторизации мост поднят, но ни к какому аккаунту не подключён и ничего не пересылает. В конце setup.sh явно печатает итог: ✅ авторизован или ⚠️ НЕ авторизован.

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

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

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

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

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

Учтите: любой участник Telegram-группы видит в ней все зеркалированные MAX-чаты (по теме на чат), а не какой-то один. Доступ к самой группе — чувствительная вещь, раздавайте его осознанно.

Веб-панель работает по 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 на хосте — бэкап этой папки достаточен для переноса на другой сервер.

Прокси для Telegram

Если сервер выходит в Telegram только через прокси (например, домашний сервер, где прямой доступ к api.telegram.org закрыт) — укажите его. MAX при этом всегда идёт напрямую, через прокси гоняется только Telegram-трафик. Форматы: socks5://[логин:пароль@]хост:порт или http://[логин:пароль@]хост:порт.

Задать можно тремя способами:

• При установке — setup.sh спрашивает про прокси ещё до проверки связи (иначе на proxy-only хосте проверка Telegram ложно упала бы), и тут же проверяет доступность через него.
• В .env — переменная TELEGRAM_PROXY.
• В веб-панели — вкладка Configuration → «Telegram-прокси»: кнопка «Проверить» тестирует связь через прокси вживую, «Сохранить и перезапустить» применяет его. Значение сохраняется в ./data и перекрывает .env; применяется после короткого перезапуска контейнера (Telegraf задаёт прокси при старте, на лету не подменяется).

Если что-то не работает

Сама установка проходит на любом Ubuntu/Debian (проверено вплоть до Debian 13 trixie) даже на VPS с менее чем 1 ГБ RAM — окружение почти никогда не причём. Быстрее всего локализовать проблему по одному признаку — проявляется ли бот в вашей Telegram-группе хоть как-то: приходит ли после старта его сообщение «✅ Telemax подключён к этой группе», заводятся ли темы под MAX-чаты.

• Бота в группе не видно вообще (ни стартового сообщения, ни тем) — он не достучался до Telegram или до группы: пункты 1–3.
• Бот активен, но сообщения из MAX не приходят — почти всегда не завершена авторизация MAX: пункт 4.

Все команды — из папки установки (cd /opt/telemax):

1. Бот не достучался до Telegram (частый случай на хостингах в РФ). На dual-stack серверах IPv6-маршрут до api.telegram.org бывает заблокирован, а система по умолчанию пробует сначала именно IPv6 — бот виснет на подключении, в группе полная тишина. Свежие версии форсируют IPv4 сами, так что первым делом обновитесь: /version в группе → «Обновить» (или ./update.sh). Если по какой-то причине не помогло — как временный обходной путь можно прибить IPv4-адрес Telegram в /etc/hosts: 149.154.167.220 api.telegram.org.

2. Контейнер не запущен.

   docker ps
   

   Если в списке пусто — посмотрите причину падения (docker compose logs --tail=50) и поднимите заново: docker compose up -d.

3. Бот добавлен в группу без нужных прав. Он должен быть в группе администратором с правом «Управление темами» (Manage Topics) — без него бот не может создавать темы под MAX-чаты. И TARGET_TELEGRAM_GROUP в .env должен быть id именно этой группы. Если прав не хватает, бот сам напишет об этом в группу.

4. Не завершена авторизация MAX — самая частая причина, когда бот в группе есть, а переписки нет. Запрос номера и SMS-кода легко пропустить: он идёт после сборки (см. «Первая авторизация»). Проверьте логи:

   docker compose logs --tail=30
   

   Если нет строки Resumed session for +… — аккаунт не подключён. Проще всего добить авторизацию, запустив ./setup.sh ещё раз: он увидит, что MAX не авторизован, и предложит ввести номер и код прямо в консоли. То же самое можно сделать в веб-панели: откройте https://<адрес-сервера>:порт, введите API_KEY, затем номер и код из SMS.

5. Не видно ключа веб-панели. Он в .env:

   grep API_KEY .env
   

   Либо спросите у бота командой /apikey в вашей Telegram-группе.

6. Не открывается веб-панель. Она работает по HTTPS (https://…, не http://) с самоподписанным сертификатом — браузер один раз предупредит, жмите «Дополнительно» → «Перейти на сайт». Если сервер за NAT/файрволом — проверьте, что порт (по умолчанию 3000) проброшен/открыт.

7. Установка встала на проверке связи. setup.sh в начале проверяет доступность MAX и Telegram и падает с явной ошибкой, если один из серверов недоступен (файрвол хостинга или гео-блокировка). Если установка остановилась именно на этой проверке — дело в сети сервера.

Не нашли причину — заводите Issue с выводом docker compose logs --tail=50 (ключи/токены из .env не прикладывайте).

Обновление

Раз в сутки (в случайное время) бот сам проверяет, есть ли на 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-группы. Проект не несёт ответственности за сохранность, утечку или неправомерное использование этих данных — обеспечение их безопасности (доступ к серверу, шифрование диска, ротация логов и т.д.) целиком на вас.

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

Нашли баг или есть вопрос — напишите боту @TelemaxSvv_bot прямо в 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

Телеметрия

Чтобы понимать, сколько инстансов моста реально работает, раз в сутки бот отправляет анонимный пинг: случайный идентификатор установки (UUID, генерируется один раз и хранится в .data/install-id) и текущую версию. Никаких номеров телефонов, содержимого сообщений, IP или иных персональных данных не передаётся и не хранится — только «эта установка жива, версия такая-то».

Отключить полностью — добавьте в .env:

TELEMETRY=off

и перезапустите контейнер (docker compose up -d). После этого бот не отправляет ничего.