Пересылка сообщений из мессенджера 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)

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 → JSON-объект авторизации; для MAX_TOKEN возьмите значение поля token, а не весь объект
   • __oneme_device_id → это ваш MAX_DEVICE_ID

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

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

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

cp .env.example .env

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

Запустите бота (можно без MAX_CHAT_IDS/MAX_EXCLUDE_CHAT_IDS — тогда пересылается всё) и посмотрите в логах при подключении строку:

Known chats: {100: 'Dev Team', 99: 'DM:55', -758: 'Новости'}

Это словарь {ID чата: название} для всех чатов аккаунта — найдите нужное название и возьмите его числовой ключ. Если чат новый и в этот список не попал, дождитесь сообщения из него и посмотрите строку New message: chat=<ID> ... в логе.

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

docker-compose up -d

Готовый образ публикуется GitHub Actions в GHCR:

docker pull ghcr.io/aist/max2tg:latest
docker run -d \
  --name max2tg \
  --restart unless-stopped \
  --env-file .env \
  -v "$(pwd)/logs:/app/logs" \
  ghcr.io/aist/max2tg:latest

Workflow публикует образ на push в main и при ручном запуске. Основные теги образа: latest и sha-<commit>.

Если пакет создаётся в GHCR впервые и GitHub оставил его приватным, откройте package settings и переключите visibility в Public; после этого образ будет доступен для docker pull без логина.

Логи Docker (stdout):

docker-compose logs -f

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

tail -f logs/max2tg.log

Остановка:

docker-compose down

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

docker-compose up -d --build

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

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

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

Создайте файл /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 текст или вложение: фото, документ, видео, голосовое или аудио. Подпись к файлу уходит текстом сообщения. Telegram отдаёт ботам файлы размером до 20 МБ — более крупные вложения переслать не получится

Логи и отладочные дампы содержат вашу переписку — учитывайте это, прежде чем куда-то их отправлять.

Обычные логи (logs/max2tg.log и вывод docker-compose logs) содержат: начало текста каждого пересланного сообщения, имена контактов и названия чатов, имена файлов. Токена аккаунта Max там нет, подписанные ссылки на файлы с недавних версий обрезаются до host/path.

При DEBUG=true в папку debug/ дополнительно выгружаются сырые JSON-дампы: snapshot.json (профиль, список чатов, участники), dispatch_*.json (первые 20 входящих событий целиком, вместе с телами сообщений) и contacts_response.json. Маскирование к ним не применяется. Включайте отладку только когда она нужна, и удаляйте debug/ после — сами файлы не удаляются и не перезаписываются.

logs/ и debug/ исключены из git и из Docker-образа, но если вы прикладываете лог к issue или отправляете его кому-то — просмотрите его перед этим.

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
├── 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  # тесты уведомлений о статусе соединения
├── 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)

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.

• 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) — text or an attachment (photo, file, video, voice)
• 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

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

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 → authorization JSON object; use the token field value as MAX_TOKEN, not the whole object
   • __oneme_device_id → this is your MAX_DEVICE_ID

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

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

Copy the example config and fill in the values:

cp .env.example .env

.env contents:

Start the bot (without MAX_CHAT_IDS/MAX_EXCLUDE_CHAT_IDS it forwards everything) and look for this line in the logs on connect:

Known chats: {100: 'Dev Team', 99: 'DM:55', -758: 'News'}

It's a {chat ID: name} dict of every chat on the account - find the name you need and take its numeric key. If the chat is new and wasn't in that list yet, wait for a message from it and check the New message: chat=<ID> ... log line.

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

docker-compose up -d

The prebuilt image is published by GitHub Actions to GHCR:

docker pull ghcr.io/aist/max2tg:latest
docker run -d \
  --name max2tg \
  --restart unless-stopped \
  --env-file .env \
  -v "$(pwd)/logs:/app/logs" \
  ghcr.io/aist/max2tg:latest

The workflow publishes the image on pushes to main and on manual runs. Main image tags are latest and sha-<commit>.

If this is the first GHCR package publication and GitHub leaves the package private, open the package settings and change visibility to Public; after that the image can be pulled without logging in.

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

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

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

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

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

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 and send back either text or an attachment (photo, document, video, voice or audio) to the corresponding Max chat. A file's caption is forwarded as the message text. Telegram caps bot file downloads at 20 MB, so larger attachments cannot be forwarded

Logs and debug dumps contain your conversations — keep that in mind before sending them anywhere.

Regular logs (logs/max2tg.log and docker-compose logs output) contain: the beginning of each forwarded message, contact and chat names, file names. They hold no Max account token, and signed file URLs are trimmed to host/path.

With DEBUG=true raw JSON dumps are additionally written to debug/: snapshot.json (profile, chat list, participants), dispatch_*.json (the first 20 incoming events in full, message bodies included) and contacts_response.json. No masking is applied to these. Enable debugging only while you need it and delete debug/ afterwards — the files are never removed or overwritten on their own.

logs/ and debug/ are excluded from git and from the Docker image, but if you attach a log to an issue or send it to someone, review it first.

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

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)

MIT