telegram-multitool

CLI-инструмент для работы с Telegram:

• создание и использование пользовательской сессии;
• просмотр списка чатов;
• удаление своих сообщений;
• экспорт истории и непрочитанных сообщений в HTML;
• скрытие ваших активных сторис от конкретного пользователя (через privacy rules);
• экспорт сообщений для сценария copy-private-group.

Требования

• Python 3.9+ (рекомендуется 3.10+)
• Telegram api_id и api_hash (получаются на my.telegram.org)

Проект используется как локальное desktop CLI-приложение (без Telegram Bot API и без серверного деплоя).

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

1. Создай виртуальное окружение:

   python3 -m venv venv

2. Активируй его:

   source venv/bin/activate

3. Установи зависимости:

   pip install -r requirements.txt

4. Создай .env из примера и заполни значения:

   cp .env.example .env

   Минимально нужны:

   • API_ID
   • API_HASH

5. Создай сессию:

   venv/bin/python script.py create-session

   По умолчанию используется имя сессии session.

Общая форма запуска

venv/bin/python script.py [--session SESSION_NAME] <command> [options]

Пример с кастомной сессией:

venv/bin/python script.py --session my_session create-session

Основные команды

Создать/проверить сессию

venv/bin/python script.py create-session
venv/bin/python script.py --session my_session create-session

Вывести список чатов (с экспортом в HTML)

venv/bin/python script.py list-chats
venv/bin/python script.py list-chats --items-per-page 50
venv/bin/python script.py list-chats --no-open-browser

Для супергрупп с разделами (topics) в HTML показываются вложенные разделы и составные ID формата chat_id:topic_id.

Удалить мои сообщения в чате

venv/bin/python script.py delete-my-messages --chat-id -idGroup
venv/bin/python script.py delete-my-messages --chat-id -idGroup --batch-size 100 --delay 1

Экспорт recent actions в HTML

venv/bin/python script.py export-history --chat-id -idGroup
venv/bin/python script.py export-history --chat-id -idGroup --limit 200

Экспорт непрочитанных сообщений в HTML (без read receipts)

venv/bin/python script.py export-unread --chat-id -idGroup
venv/bin/python script.py export-unread --chat-id -idGroup --limit 300 --items-per-page 100
venv/bin/python script.py export-unread --chat-id -idGroup --no-open-browser

Экспорт сообщений для copy-private-group

venv/bin/python script.py copy-private-group --chat-id -idGroup
venv/bin/python script.py copy-private-group --chat-id -idGroup:idFolder
venv/bin/python script.py copy-private-group --chat-id -idGroup:idFolder:idMessage
venv/bin/python script.py copy-private-group --chat-id https://t.me/c/idForumGroup/idFolder
venv/bin/python script.py copy-private-group --chat-id https://t.me/c/idForumGroup/idFolder/idMessage
venv/bin/python script.py copy-private-group --chat-id -idGroup --message-id idMessage
venv/bin/python script.py copy-private-group --chat-id -idGroup --limit 500 --items-per-page 100
venv/bin/python script.py copy-private-group --chat-id -idGroup --no-open-browser

Поддерживается необязательный message_id: при передаче chat_id:topic_id:message_id или ссылки t.me/c/.../topic_id/message_id экспорт ограничивается сообщениями до указанного message_id. Также можно передать --message-id отдельным аргументом (для автоматизаций); если заданы оба варианта, приоритет у --message-id.

Скрыть ваши активные сторис от пользователя по username

venv/bin/python script.py hide-stories --username some_user
venv/bin/python script.py hide-stories --username @some_user

Справка по CLI

Общая:

venv/bin/python script.py --help

По конкретной команде:

venv/bin/python script.py list-chats --help
venv/bin/python script.py delete-my-messages --help
venv/bin/python script.py export-history --help
venv/bin/python script.py export-unread --help
venv/bin/python script.py copy-private-group --help
venv/bin/python script.py hide-stories --help

Что не коммитить в Git

В проекте уже настроен .gitignore для локальных секретов, виртуального окружения, кэша и артефактов экспорта. Обычно в репозиторий не должны попадать:

• .env и любые файлы с секретами;
• файлы сессий Telegram (*.session, *.session-journal);
• venv/;
• __pycache__/, *.pyc;
• служебные директории IDE и macOS.