max2tg

Пересылка сообщений из мессенджера Max (max.ru) в Telegram в реальном времени — с возможностью отвечать обратно.

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

1. Этот проект является независимым, неофициальным и не связан с разработчиками мессенджера Max (или любой другой сторонней организацией). Авторы Max не одобряют, не поддерживают и не несут ответственности за этот код.

2. Программа предоставляется "как есть" (AS IS), без каких-либо гарантий — явных или подразумеваемых, включая, но не ограничиваясь гарантиями товарности, пригодности для конкретной цели или отсутствия ошибок.

3. Авторы не несут ответственности за любые прямые, косвенные, случайные, специальные или последствия ущерба, возникшие в связи с использованием этого ПО, включая потерю данных, доходов или другие убытки, даже если автор был уведомлён о возможности такого ущерба.

4. Использование этого ПО осуществляется исключительно на ваш страх и риск. Рекомендуется самостоятельно проверить код на безопасность и соответствие местному законодательству перед использованием.

5. Этот проект создан в образовательных и исследовательских целях. Авторы не поощряют и не рекомендуют использование для обхода требований государственных органов или нарушения пользовательских соглашений третьих сторон.

English version below

---

Возможности

• Пересылка текстовых сообщений, фото, видео, файлов, аудио, стикеров, контактов, геолокаций и ссылок
• Поддержка пересланных и цитируемых сообщений (forward / reply)
• Разное оформление для личных и групповых чатов
• Ответ из Telegram обратно в Max (опционально, через inline-кнопку)
• Уведомления о статусе соединения с Max — при запуске, потере связи и восстановлении (с троттлингом, чтобы не спамить)
• Поддержка SOCKS5-прокси для подключения к Telegram
• Работает как userbot — подключается к вашему аккаунту Max через WebSocket
• Docker-ready: разворачивается одной командой

Требования

• Python 3.12+
• Аккаунт в Max (web.max.ru)
• Telegram-бот (создаётся через @BotFather)

Получение credentials

Max: токен и device ID

1. Откройте web.max.ru в Chrome/Firefox и войдите в свой аккаунт
2. Откройте DevTools: F12 (или Cmd+Option+I на macOS)
3. Перейдите во вкладку Application (Chrome) или Storage (Firefox)
4. В левой панели: Local Storage → https://web.max.ru
5. Найдите и скопируйте значения:
   • __oneme_auth → это ваш MAX_TOKEN
   • __oneme_device_id → это ваш MAX_DEVICE_ID

Важно: не делитесь этими значениями — они дают полный доступ к вашему аккаунту Max.

Telegram: токен бота и chat ID

1. Напишите @BotFather в Telegram → /newbot → следуйте инструкциям
2. Скопируйте полученный токен → это ваш TG_BOT_TOKEN
3. Узнайте свой chat ID: напишите @userinfobot → он ответит вашим ID → это TG_CHAT_ID
4. Важно: напишите вашему боту /start, чтобы он мог вам отправлять сообщения

Настройка

Скопируйте пример конфигурации и заполните значения:

cp .env.example .env

Содержимое .env:

Переменная	Обязательная	Описание
MAX_TOKEN	да	Токен авторизации Max
MAX_DEVICE_ID	да	ID устройства Max
MAX_CHAT_IDS	нет	список ID чатов Max, разделенных запятой
TG_BOT_TOKEN	да	Токен Telegram-бота
TG_CHAT_ID	да	ID чата, куда пересылать сообщения
DEBUG	нет	true — подробные логи + дамп JSON в debug/
REPLY_ENABLED	нет	true — разрешить ответы из Telegram в Max
PLUGINS_ENABLED	нет	false — отключить плагины из app/plugins/ (по умолчанию true)
UNREAD_ONLY	нет	true — пересылать только непрочитанные (если прочитали в Max — в TG не придёт)
UNREAD_DELAY_SEC	нет	Задержка в секундах перед проверкой прочитанности (по умолчанию 2)
SKIP_MUTED	нет	true — не пересылать из заглушённых чатов Max («без звука»)
MUTED_DIGEST_ENABLED	нет	true — накапливать сообщения из заглушённых чатов и выдавать по /muted или кнопке 📭 Заглушённые
LOG_DIR	нет	Путь к директории логов (по умолчанию logs)
TG_PROXY	нет	SOCKS5-прокси для Telegram (socks5://host:port)
TG_READ_TIMEOUT	нет	Таймаут чтения HTTP-ответа от Telegram, в секундах
TG_WRITE_TIMEOUT	нет	Таймаут отправки обычного запроса к Telegram, в секундах
TG_MEDIA_WRITE_TIMEOUT	нет	Таймаут загрузки медиафайлов в Telegram, в секундах. Увеличьте, если файлы отправляются повторно из-за медленного прокси

Запуск

Docker (рекомендуется для сервера)

Безопасный деплой на VPS (права на .env, SSH, 24/7): см. DEPLOY.md
Обновление токена Max и перезапуск: см. TOKEN_UPDATE.md

git clone git@github.com:Aist/max2tg.git max2tg
cd max2tg
cp .env.example .env
# отредактируйте .env

docker-compose up -d

Логи Docker (stdout):

docker-compose logs -f

Логи на диске доступны на хосте в директории ./logs/ — файл max2tg.log с ротацией по 10 МБ (хранится 5 файлов):

tail -f logs/max2tg.log

Остановка:

docker-compose down

Пересборка после обновления:

docker-compose up -d --build

Локальный запуск

Linux / macOS

git clone <repo-url> max2tg
cd max2tg

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# отредактируйте .env

python -m app.main

Windows (PowerShell)

git clone <repo-url> max2tg
cd max2tg

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

copy .env.example .env
# отредактируйте .env

python -m app.main

Windows (CMD)

git clone <repo-url> max2tg
cd max2tg

python -m venv .venv
.venv\Scripts\activate.bat
pip install -r requirements.txt

copy .env.example .env
# отредактируйте .env

python -m app.main

Запуск как systemd-сервис (Linux)

Создайте файл /etc/systemd/system/max2tg.service:

[Unit]
Description=Max to Telegram forwarder
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/max2tg
ExecStart=/opt/max2tg/.venv/bin/python -m app.main
Restart=always
RestartSec=10
EnvironmentFile=/opt/max2tg/.env

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now max2tg
sudo journalctl -u max2tg -f

Как это работает

Max (WebSocket) ──→ max2tg ──→ [SOCKS5 proxy] ──→ Telegram Bot ──→ Ваш чат
                       ↑                                              │
                       └────────── (если REPLY_ENABLED) ──────────────┘

1. Приложение подключается к Max через WebSocket как ваш аккаунт
2. Новые входящие сообщения пересылаются в указанный Telegram-чат
3. Если REPLY_ENABLED=true, под каждым сообщением появляется кнопка «Ответить» — нажав её, можно написать текст, который отправится обратно в соответствующий чат Max

Расширения (плагины)

Форк поддерживает хуки и плагины для доработки без изменения ядра:

• События: on_ready, on_message, on_message_sent, on_disconnect, on_tg_reply
• Автозагрузка модулей из app/plugins/
• Пример: app/plugins/example_logger.py

Подробнее: EXTENSIONS.md

Ваш репозиторий на GitHub

Репозиторий: github.com/erop39/max2tg (приватный)

В git не попадают: .env, logs/, debug/, .venv/ — см. .gitignore.

Клонирование (новая машина)

git clone https://github.com/erop39/max2tg.git
cd max2tg
cp .env.example .env
# заполните .env — секреты только локально
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt pytest pytest-asyncio
python -m app.main

SSH (если настроен ключ GitHub):

git clone git@github.com:erop39/max2tg.git

Ежедневная работа

git pull origin main          # получить изменения
# правки → commit → push
git add .
git commit -m "описание"
git push origin main

CI: при каждом push на main GitHub Actions запускает pytest (см. .github/workflows/ci.yml).

Обновление оригинала (upstream)

git fetch upstream
git merge upstream/main
git push origin main

Remotes: origin — ваш форк, upstream — Aist/max2tg.

Структура проекта

max2tg/
├── app/
│   ├── main.py          # точка входа
│   ├── config.py         # загрузка настроек из .env
│   ├── max_client.py     # WebSocket-клиент Max
│   ├── max_listener.py   # обработка и форматирование сообщений
│   ├── resolver.py       # кеш и резолвинг имён контактов/чатов
│   ├── tg_sender.py      # отправка сообщений в Telegram
│   ├── tg_handler.py     # обработка ответов из Telegram
│   ├── hooks.py          # реестр событий для расширений
│   └── plugins/          # пользовательские плагины
│       ├── _base.py
│       └── example_logger.py
├── tests/
│   ├── test_config.py             # тесты загрузки настроек
│   ├── test_max_client.py         # тесты клиента Max (опкоды, парсинг)
│   ├── test_max_listener.py       # тесты форматирования сообщений
│   ├── test_resolver.py           # тесты резолвинга имён контактов
│   ├── test_tg_handler.py         # тесты обработки ответов из Telegram
│   ├── test_disconnect_notify.py  # тесты уведомлений о статусе соединения
│   └── test_hooks.py              # тесты хуков и плагинов
├── EXTENSIONS.md        # руководство по расширению
├── logs/                # логи (создаётся автоматически)
├── .env.example
├── Dockerfile
├── docker-compose.yml
├── pytest.ini
└── requirements.txt

Тесты

Установите зависимости для тестирования:

pip install pytest pytest-asyncio

Запуск тестов:

pytest

Тесты покрывают:

• загрузку и валидацию конфигурации (config.py)
• парсинг сообщений и опкоды WebSocket-клиента (max_client.py)
• форматирование размеров файлов и определение типа медиа (max_listener.py)
• резолвинг имён контактов и парсинг снапшота (resolver.py)
• обработку ответов из Telegram и пересылку в Max (tg_handler.py)
• уведомления о статусе соединения и логику троттлинга (test_disconnect_notify.py)

---

max2tg (English)

Real-time message forwarding from Max messenger (max.ru) to Telegram — with optional reply support.

Disclaimer: This is an unofficial project. It is not affiliated with or endorsed by the Max development team. The application works via reverse engineering of the Max web client and may break at any time if the protocol changes. Use at your own risk. The author is not responsible for any consequences, including account suspension.

Features

• Forwards text messages, photos, videos, files, audio, stickers, contacts, locations, and links
• Supports forwarded and quoted messages (forward / reply)
• Different formatting for DMs and group chats
• Reply from Telegram back to Max (optional, via inline button)
• Connection status notifications — on startup, disconnect, and reconnect (throttled to avoid spam)
• SOCKS5 proxy support for connecting to Telegram
• Works as a userbot — connects to your Max account via WebSocket
• Docker-ready: deploy with a single command

Requirements

• Python 3.12+
• Max account (web.max.ru)
• Telegram bot (create via @BotFather)

Obtaining Credentials

Max: token and device ID

1. Open web.max.ru in Chrome/Firefox and log in
2. Open DevTools: F12 (or Cmd+Option+I on macOS)
3. Go to the Application tab (Chrome) or Storage (Firefox)
4. In the left panel: Local Storage → https://web.max.ru
5. Find and copy the values:
   • __oneme_auth → this is your MAX_TOKEN
   • __oneme_device_id → this is your MAX_DEVICE_ID

Important: do not share these values — they grant full access to your Max account.

Telegram: bot token and chat ID

1. Message @BotFather on Telegram → /newbot → follow the instructions
2. Copy the token → this is your TG_BOT_TOKEN
3. Get your chat ID: message @userinfobot → it replies with your ID → this is TG_CHAT_ID
4. Important: send /start to your bot so it can message you

Configuration

Copy the example config and fill in the values:

cp .env.example .env

.env contents:

Variable	Required	Description
MAX_TOKEN	yes	Max auth token
MAX_DEVICE_ID	yes	Max device ID
MAX_CHAT_IDS	no	Comma-separated list of Max chat IDs to listen to (all chats if unset)
TG_BOT_TOKEN	yes	Telegram bot token
TG_CHAT_ID	yes	Chat ID to forward messages to
DEBUG	no	true — verbose logs + JSON dumps to debug/
REPLY_ENABLED	no	true — enable replies from Telegram to Max
PLUGINS_ENABLED	no	false — disable plugins in app/plugins/ (default true)
UNREAD_ONLY	no	true — forward only unread messages (skip if read in Max)
UNREAD_DELAY_SEC	no	Delay before read check in seconds (default 2)
SKIP_MUTED	no	true — skip muted / do-not-disturb chats in Max
MUTED_DIGEST_ENABLED	no	true — buffer muted-chat messages and flush them via /muted or the 📭 Заглушённые button
LOG_DIR	no	Log directory path (default: logs)
TG_PROXY	no	SOCKS5 proxy for Telegram (socks5://host:port)
TG_READ_TIMEOUT	no	HTTP read timeout for Telegram responses, in seconds
TG_WRITE_TIMEOUT	no	HTTP write timeout for regular Telegram requests, in seconds
TG_MEDIA_WRITE_TIMEOUT	no	Upload timeout for media files to Telegram, in seconds. Increase if files are sent multiple times due to a slow proxy

Running

Docker (recommended for servers)

git clone git@github.com:Aist/max2tg.git max2tg
cd max2tg
cp .env.example .env
# edit .env

docker-compose up -d

Docker logs (stdout):

docker-compose logs -f

Persistent logs are available on the host in ./logs/ — file max2tg.log with rotation at 10 MB (5 files kept):

tail -f logs/max2tg.log

Stop:

docker-compose down

Rebuild after update:

docker-compose up -d --build

Local

Linux / macOS

git clone <repo-url> max2tg
cd max2tg

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# edit .env

python -m app.main

Windows (PowerShell)

git clone <repo-url> max2tg
cd max2tg

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

copy .env.example .env
# edit .env

python -m app.main

Windows (CMD)

git clone <repo-url> max2tg
cd max2tg

python -m venv .venv
.venv\Scripts\activate.bat
pip install -r requirements.txt

copy .env.example .env
# edit .env

python -m app.main

Running as a systemd service (Linux)

Create /etc/systemd/system/max2tg.service:

[Unit]
Description=Max to Telegram forwarder
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/max2tg
ExecStart=/opt/max2tg/.venv/bin/python -m app.main
Restart=always
RestartSec=10
EnvironmentFile=/opt/max2tg/.env

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now max2tg
sudo journalctl -u max2tg -f

How It Works

Max (WebSocket) ──→ max2tg ──→ [SOCKS5 proxy] ──→ Telegram Bot ──→ Your chat
                       ↑                                              │
                       └────────── (if REPLY_ENABLED) ────────────────┘

1. The app connects to Max via WebSocket using your account credentials
2. Incoming messages are forwarded to the specified Telegram chat
3. If REPLY_ENABLED=true, each message includes a "Reply" button — press it, type your response, and it gets sent back to the corresponding Max chat

Extensions (plugins)

This fork adds hooks and plugins for customization without changing core logic. See EXTENSIONS.md.

Project Structure

max2tg/
├── app/
│   ├── main.py          # entry point
│   ├── config.py         # loads settings from .env
│   ├── max_client.py     # Max WebSocket client
│   ├── max_listener.py   # message processing and formatting
│   ├── resolver.py       # contact/chat name cache and resolution
│   ├── tg_sender.py      # sends messages to Telegram
│   └── tg_handler.py     # handles replies from Telegram
├── tests/
│   ├── test_config.py             # settings loading tests
│   ├── test_max_client.py         # Max client tests (opcodes, parsing)
│   ├── test_max_listener.py       # message formatting tests
│   ├── test_resolver.py           # contact name resolution tests
│   ├── test_tg_handler.py         # Telegram reply handler tests
│   └── test_disconnect_notify.py  # connection status notification tests
├── logs/                # log files (created automatically)
├── .env.example
├── Dockerfile
├── docker-compose.yml
├── pytest.ini
└── requirements.txt

Tests

Install test dependencies:

pip install pytest pytest-asyncio

Run tests:

pytest

Test coverage:

• configuration loading and validation (config.py)
• message parsing and WebSocket opcodes (max_client.py)
• file size formatting and media type detection (max_listener.py)
• contact name resolution and snapshot parsing (resolver.py)
• Telegram reply handling and forwarding to Max (tg_handler.py)
• connection status notifications and throttle logic (test_disconnect_notify.py)

License

MIT