TgDigestBot

Daily digest of a Telegram group. The userbot collects unread messages and sends them to a configured bot for summarization — grouped by topic if the group uses Telegram's Topics feature.

Supports multiple groups — scan all your chats once and switch between them by name.

How it works

1. Logs into Telegram as your account (Telethon userbot)
2. Fetches only messages not yet processed (tracked via state.json)
3. If the group has Topics — sends a digest section per topic
4. Saves messages to a timestamped file in digests/
5. Sends a structured prompt + file path to BOT_USERNAME for summarization

Note: This bot is designed to work with an AI agent bot (e.g. Claude Code agent) that has access to the local filesystem and can read the saved digest file. The BOT_USERNAME must be a bot that understands the digest prompt and can read files from the path sent.

Prerequisites

• Python 3.11+
• A Telegram account
• An AI agent bot running locally with filesystem access (receives and summarizes digests)

Installation

git clone https://github.com/JamesVynn/TgDigestBot.git
cd TgDigestBot
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configuration

cp .env.example .env
nano .env  # fill in all values

.env variables:

API_ID=          # from https://my.telegram.org
API_HASH=        # from https://my.telegram.org
GROUP_USERNAME=  # @username or numeric ID of the group (e.g. -1001234567890)
BOT_USERNAME=    # @username of the bot that receives and summarizes digests
SCHEDULE_HOUR=20 # daily digest time (UTC)
SCHEDULE_MINUTE=0

How to get API_ID / API_HASH:

1. Go to https://my.telegram.org
2. Log in with your phone number
3. Open "API development tools" → create an app → copy api_id and api_hash

How to find your group ID from a Telegram link: https://t.me/c/4390855861/151 → ID is -1004390855861 (prefix -100 to the number in the URL)

First run (authentication)

source venv/bin/activate
python3 main.py --auth
# enter your phone number and confirmation code

The session is saved to userbot_session.session and won't prompt again.

Running

python3 main.py                          # Start scheduler (daily digest at configured UTC time)
python3 main.py --now                    # Run full digest immediately across all topics
python3 main.py --topic "Name"           # Digest for a single topic (partial name match)
python3 main.py --topic "Name" --only-new  # Show only topics not seen in previous digests
python3 main.py --unread                 # Show unread message count per topic
python3 main.py --mark-read              # Mark ALL topics as read in Telegram + update state.json
python3 main.py --commit                 # Promote pending state after a --now digest is summarized
python3 main.py --auth                   # First-time Telegram authentication
python3 main.py --list-groups            # Scan all dialogs and save name→ID to groups.json
python3 main.py --group-name "Name" ...  # Use a different group by name (partial match)

--commit explained: --now writes a pending state that becomes permanent only after you confirm the digest was summarized correctly. Run --commit to finalize. This prevents marking messages as read if something failed.

Multi-group usage

# First, scan and save all your chats (creates groups.json)
python3 main.py --list-groups

# Then use any group by partial name instead of changing .env
python3 main.py --group-name "My Group" --unread
python3 main.py --group-name "My Group" --now
python3 main.py --group-name "My Group" --topic "general"

Group names are resolved from groups.json. Re-run --list-groups after joining new chats.

As a systemd service:

# Edit tgdigestbot.service — replace YOUR_LINUX_USER
sudo cp tgdigestbot.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable tgdigestbot
sudo systemctl start tgdigestbot
sudo systemctl status tgdigestbot

File structure

TgDigestBot/
├── main.py                    # entry point, scheduler, CLI flags
├── digest.py                  # core logic — fetch messages, send to bot
├── groups.py                  # multi-group support — name→ID registry
├── state.py                   # tracks last processed message ID per topic
├── influencers.py             # tracked user IDs → display names
├── memory.py                  # digest memory for --only-new comparisons
├── state.json                 # auto-created, gitignored
├── state_pending.json         # write-ahead buffer for --now flow, gitignored
├── groups.json                # chat name→ID map, auto-created, gitignored
├── digests/                   # saved digest text files (auto-created)
├── memory/                    # previous digest memory (auto-created)
├── userbot_session.session    # Telegram session, gitignored
├── .env                       # your secrets, gitignored
├── .env.example               # config template
├── requirements.txt
└── tgdigestbot.service