Telegram Media Downloader¶

Automated Telegram media downloader daemon with multi-source support, flexible filtering, and Docker deployment.

Ebook Forum Archiving

Automatically download ebooks from Telegram forum topics as they're posted

Ebook Example
YouTube Channel Mirrors

Archive YouTube content shared in Telegram channels

YouTube Example
News Media Aggregation

Collect media from news channels automatically

News Example
Personal Chat Backups

Backup media from your personal chats and saved messages

Backup Example

Quick Start¶

Get started in 5 minutes with Docker Compose.

Features¶

Multi-Source Support

Download from channels, groups, forum topics, and private chats with flexible URL patterns
Advanced Filtering

Filter by file extensions, size ranges, date ranges, and filename patterns
Smart Organization

Organize with per-source folders, duplicate detection, and conflict resolution
Daemon Mode

Continuous background operation with configurable check intervals
Notifications

Get alerts via Discord webhooks and generic HTTP POST for errors and completions
Docker Ready

Multi-platform images (amd64 + arm64), Docker Compose setup, health checks
Secure

Session protection, path traversal prevention, non-root container
Flexible Configuration

Environment variables or TOML configuration with validation

Featured Use Case: Ebook Forum Downloader¶

Automatically download ebooks from Telegram forum topics as they're posted. Set it up once, run continuously in Docker, get notifications when new books arrive.

Example: Follow ebook release forums, filter for PDF/EPUB/MOBI files, organize by source, receive Discord notifications on new releases.

# docker-compose.yml - Complete example in examples/ebook-forum.yml
services:
  telegram-downloader:
    image: rfsbraz/telegram-downloader:latest
    restart: unless-stopped
    environment:
      - TDL_API_ID=YOUR_API_ID
      - TDL_API_HASH=YOUR_API_HASH
      - TDL_PHONE_NUMBER=YOUR_PHONE
      - TDL_DAEMON_ENABLED=true
      - TDL_SOURCES_0_URL=https://t.me/c/1234567890/123
      - TDL_SOURCES_0_FILTERS_EXTENSIONS=.pdf,.epub,.mobi
    volumes:
      - ./ebooks:/downloads

Result: Ebooks organized by forum topic, duplicates skipped, new releases downloaded every 5 minutes, Discord notifications on completion.

View Complete Ebook Example

Documentation¶

Quick Start Guide

5-minute Docker Compose setup with step-by-step instructions
Configuration Reference

Complete reference for all settings and environment variables
Troubleshooting Guide

Common errors and solutions with debugging tips
Deployment Guide

Production best practices and deployment checklist

Example Use Cases¶

All examples include complete Docker Compose configurations:

Ebook Forum - Automatic ebook downloads from forum topics (featured)
YouTube Archiver - Mirror YouTube channels shared in Telegram
News Aggregator - Aggregate media from news channels
Personal Backup - Backup personal chats and saved messages

View All Examples

Configuration Highlights¶

Multiple Sources¶

- TDL_SOURCES_0_URL=https://t.me/channel1
- TDL_SOURCES_1_URL=https://t.me/c/1234/567  # Forum topic
- TDL_SOURCES_2_URL=https://t.me/me  # Saved messages

Flexible Filtering¶

- TDL_SOURCES_0_FILTERS_EXTENSIONS=.pdf,.epub,.mobi
- TDL_SOURCES_0_FILTERS_MIN_SIZE=100KB
- TDL_SOURCES_0_FILTERS_MAX_SIZE=500MB
- TDL_SOURCES_0_FILTERS_MIN_DATE=2026-01-01

Notifications¶

- TDL_NOTIFICATIONS_ENABLED=true
- TDL_NOTIFICATIONS_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
- TDL_NOTIFICATIONS_DETAIL_LEVEL=summary

See Configuration Reference for complete documentation.

Installation¶

Docker HubGitHub Container Registry

docker pull rfsbraz/telegram-downloader:latest

docker pull ghcr.io/rfsbraz/telegram-downloader:latest

Multi-platform support:

linux/amd64 (Intel/AMD x86_64)
linux/arm64 (Raspberry Pi 4+, AWS Graviton, Apple M1/M2)

Common Issues¶

FloodWait Errors

Telegram rate limiting - daemon automatically retries. Reduce check frequency if persistent.

PEER_ID_INVALID

Invalid source URL or no access to source. Verify URL and permissions.

Health Check Failing

Check logs for errors and verify daemon is running properly.

See Troubleshooting Guide for detailed solutions.

Contributing¶

Contributions welcome! Please read CONTRIBUTING.md first.

License¶

MIT License - see LICENSE file for details.

Acknowledgments¶

Built with:

Pyrogram - Telegram MTProto API framework
Pydantic - Data validation
PyYAML - Configuration parsing

Support¶

Issues: GitHub Issues for bug reports and feature requests
Discussions: GitHub Discussions for questions and community support
Documentation: Browse the guides in the navigation menu

Star this repo if it helps you!