Ebook Forum Downloader¶

Automatically download ebooks from Telegram forum topics as they're posted. Perfect for building a personal ebook library from release forums.

Use Case¶

Perfect For

Book collectors and readers
Students and researchers
Digital library curation
Following ebook release forums

Key Features¶

Ebook-Specific Filtering

Automatically filters for PDF, EPUB, MOBI, and AZW3 files
Organized by Topic

Each forum topic downloads to its own folder
Discord Notifications

Get notified when new ebooks are downloaded
Duplicate Detection

Automatically skips files you already have

Quick Start¶

Prerequisites¶

Docker and Docker Compose installed
Telegram API credentials from my.telegram.org/apps
Discord webhook URL (optional but recommended)
Member of the ebook forum/channel

Setup Steps¶

1. Create project directory:

mkdir telegram-ebook-downloader
cd telegram-ebook-downloader
mkdir ebooks sessions

2. Create docker-compose.yml:

# Ebook Forum Downloader - Featured Use Case
#
# Downloads ebooks from forum topics with PDF/EPUB/MOBI filtering.
# Perfect for following ebook release forums and building a personal library.

version: '3.8'

services:
  telegram-downloader:
    image: rfsbraz/telegram-downloader:latest
    container_name: telegram-ebook-downloader
    restart: unless-stopped

    environment:
      # Telegram API credentials (get from https://my.telegram.org/apps)
      - TDL_API_ID=YOUR_API_ID
      - TDL_API_HASH=YOUR_API_HASH
      - TDL_PHONE_NUMBER=YOUR_PHONE_NUMBER

      # Daemon: Check every 5 minutes
      - TDL_DAEMON_ENABLED=true
      - TDL_DAEMON_CHECK_INTERVAL=300

      # Notifications: Discord webhook for completion updates
      - TDL_NOTIFICATIONS_ENABLED=true
      - TDL_NOTIFICATIONS_DETAIL_LEVEL=summary
      - TDL_NOTIFICATIONS_DISCORD_WEBHOOK_URL=YOUR_DISCORD_WEBHOOK_URL

      # Source: Ebook forum topic (replace with your forum URL)
      - TDL_SOURCES_0_URL=https://t.me/c/1234567890/123
      - TDL_SOURCES_0_NAME=Ebook Releases
      - TDL_SOURCES_0_FILTERS_EXTENSIONS=.pdf,.epub,.mobi,.azw3
      - TDL_SOURCES_0_FILTERS_MIN_SIZE=100KB
      - TDL_SOURCES_0_FILTERS_MAX_SIZE=500MB

    volumes:
      - ./ebooks:/downloads
      - ./sessions:/.sessions

    healthcheck:
      test: ["CMD", "python3", "/app/healthcheck.py"]
      interval: 2m
      timeout: 10s

3. Configure your settings:

Replace these placeholders:

Placeholder	Get From	Example
`YOUR_API_ID`	https://my.telegram.org/apps	`12345678`
`YOUR_API_HASH`	https://my.telegram.org/apps	`abcdef123...`
`YOUR_PHONE_NUMBER`	Your phone with country code	`+1234567890`
`YOUR_DISCORD_WEBHOOK_URL`	Discord server settings	`https://discord.com/api/webhooks/...`
`https://t.me/c/1234567890/123`	Your forum topic URL	Copy from Telegram

Finding Forum Topic URL

Open forum topic in Telegram Desktop
Right-click topic → Copy Link
URL format: https://t.me/c/CHAT_ID/TOPIC_ID

4. Start the downloader:

docker compose up -d

5. First-time authentication:

# View logs
docker compose logs -f

# Enter verification code when prompted
# Check your Telegram app for the code

6. Verify it's working:

# Check service status
docker compose ps

# Should show "healthy" status after ~1 minute

# Check downloads
ls -lh ebooks/

Configuration Details¶

File Filtering¶

The example configuration filters for ebooks:

- TDL_SOURCES_0_FILTERS_EXTENSIONS=.pdf,.epub,.mobi,.azw3
- TDL_SOURCES_0_FILTERS_MIN_SIZE=100KB
- TDL_SOURCES_0_FILTERS_MAX_SIZE=500MB

Why These Settings?

Extensions: Common ebook formats
Min Size (100KB): Filters out tiny files (likely not books)
Max Size (500MB): Reasonable limit for ebooks with images

Check Interval¶

- TDL_DAEMON_CHECK_INTERVAL=300  # 5 minutes

The daemon checks for new ebooks every 5 minutes. This is a good balance between:

Responsiveness: New books appear quickly
API Usage: Avoids Telegram rate limiting
Resource Usage: Minimal CPU and network usage

Notifications¶

- TDL_NOTIFICATIONS_ENABLED=true
- TDL_NOTIFICATIONS_DETAIL_LEVEL=summary
- TDL_NOTIFICATIONS_DISCORD_WEBHOOK_URL=YOUR_DISCORD_WEBHOOK_URL

You'll receive Discord notifications when:

New ebooks are downloaded
Errors occur (authentication, network, etc.)
Daemon status changes

Expected Results¶

Folder Structure¶

ebooks/
└── Ebook Releases/          # Named from TDL_SOURCES_0_NAME
    ├── Book Title 1.pdf
    ├── Book Title 2.epub
    ├── Book Title 3.mobi
    └── Book Title 4.azw3

Discord Notifications¶

You'll receive messages like:

Telegram Downloader - Summary

Download completed

Downloaded: 3 new ebooks

Source: Ebook Releases

Time: 2026-01-21 10:30:00

Logs¶

docker compose logs --tail=50

Healthy logs look like:

[INFO] Daemon started, checking every 300 seconds
[INFO] Checking source: Ebook Releases
[INFO] Found 3 new messages
[INFO] Downloading: Book Title 1.pdf (2.5 MB)
[INFO] Downloaded: Book Title 1.pdf
[INFO] Notification sent to Discord
[INFO] Cycle complete, waiting 300 seconds

Customization Options¶

Multiple Forum Topics¶

Add more sources by incrementing the index:

# First topic
- TDL_SOURCES_0_URL=https://t.me/c/1234567890/123
- TDL_SOURCES_0_NAME=Fiction Ebooks
- TDL_SOURCES_0_FILTERS_EXTENSIONS=.pdf,.epub,.mobi

# Second topic
- TDL_SOURCES_1_URL=https://t.me/c/1234567890/456
- TDL_SOURCES_1_NAME=Technical Books
- TDL_SOURCES_1_FILTERS_EXTENSIONS=.pdf

# Third topic
- TDL_SOURCES_2_URL=https://t.me/c/1234567890/789
- TDL_SOURCES_2_NAME=Comics
- TDL_SOURCES_2_FILTERS_EXTENSIONS=.cbr,.cbz,.pdf

Genre-Specific Filtering¶

Filter by filename patterns:

# Only download Python books
- TDL_SOURCES_0_FILTERS_PATTERNS=*python*,*Python*,*PYTHON*

# Only download fiction
- TDL_SOURCES_0_FILTERS_PATTERNS=*novel*,*fiction*,*story*

Date-Based Filtering¶

Only download recent posts:

- TDL_SOURCES_0_FILTERS_MIN_DATE=2026-01-01  # Only 2026 onwards

Adjust Check Frequency¶

# More responsive (check every minute)
- TDL_DAEMON_CHECK_INTERVAL=60

# Less aggressive (check every 10 minutes)
- TDL_DAEMON_CHECK_INTERVAL=600

# Very light (check every hour)
- TDL_DAEMON_CHECK_INTERVAL=3600

Rate Limiting

Checking too frequently (< 60 seconds) may trigger Telegram rate limiting (FloodWait errors). The daemon automatically handles these, but they slow down downloads.

Notification Detail Levels¶

# Minimal: Just success/failure
- TDL_NOTIFICATIONS_DETAIL_LEVEL=minimal

# Summary: Include file counts and errors (recommended)
- TDL_NOTIFICATIONS_DETAIL_LEVEL=summary

# Detailed: Include filenames and full error messages
- TDL_NOTIFICATIONS_DETAIL_LEVEL=detailed

Troubleshooting¶

No ebooks being downloaded

Check these:

Verify you're a member of the forum/channel
Check source URL is correct: docker compose logs | grep "source"
Verify file filters match forum content
Check for FloodWait errors in logs

FloodWait errors

Solution: Increase check interval

- TDL_DAEMON_CHECK_INTERVAL=600  # 10 minutes

Authentication failed

Solution: Delete sessions and re-authenticate

docker compose down
rm -rf sessions/*
docker compose up -d
docker compose logs -f
# Enter verification code when prompted

See Troubleshooting Guide for more solutions.

Performance¶

Resource Usage¶

Metric	Typical Usage	Notes
CPU	<5% average	Spikes during downloads
Memory	150-250 MB	Depends on file sizes
Network	Varies	Based on download activity
Disk I/O	Low	Only during downloads

Scalability¶

Single topic: Handles 1000s of ebooks easily
Multiple topics: 5-10 sources work well on modest hardware
Large forums: Consider increasing check interval to reduce load

Production Deployment¶

Production Best Practices

Use .env file for secrets (not hardcoded)
Set resource limits in docker-compose.yml
Configure log rotation
Set up automated backups of sessions folder
Monitor with health checks

See Production Deployment Guide for detailed setup.

Complete Configuration File¶

Download the complete example:

Download ebook-forum.yml

Personal Chat Backup - Backup your saved ebooks
News Aggregator - Similar multi-source setup
YouTube Archiver - Archive video content

Need Help?¶

Questions?

See Configuration Reference for all settings
Check Troubleshooting Guide for common issues
Open an issue on GitHub