TelegramMediaRelayBot is a self-hosted Telegram bot that downloads media from 1000+ platforms (via yt-dlp and gallery-dl) and forwards it to your contacts. You send a link, it fetches the media and passes it to the people you pick. Because it runs on your own machine, the files and your contact list stay off third-party servers, which also lets you share from platforms your contacts don't use.
- Multi-platform downloads: yt-dlp for video, gallery-dl for galleries, run as a fallback chain. Full list of supported sites.
- Contact forwarding: a contact list lives inside the bot, and downloaded media is forwarded automatically, with per-contact and per-link privacy rules.
- Large files up to 2 GB: with an optional local Telegram Bot API server, media is streamed from disk instead of buffered in memory.
- Resumable queue: pending downloads are persisted, so a crash or reboot never loses a request.
- Proxy support: HTTP, SOCKS5, or Tor, with per-site rules that send some domains through a proxy and others directly.
- Self-hosted: the bot runs entirely on your own infrastructure, with no third-party services in the loop.
| Layer | Technology |
|---|---|
| Runtime | .NET 10 |
| Bot framework | Telegram.Bot 22.10.2 |
| Language | C# 14 |
| Database | SQLite (Dapper + FluentMigrator) |
| Media engines | yt-dlp, gallery-dl |
| Container | Docker / docker-compose |
| License | AGPL-3.0 |
- Self-healing long polling: the update loop runs as a hosted service that logs and skips a failing update and restarts on error, so the bot can't silently stop responding.
- Modular download backends: yt-dlp and gallery-dl sit behind one
IMediaDownloaderinterface and run as an ordered fallback chain, so adding a backend means adding one class. - Per-host proxy routing: named proxies resolved per download host from typed, startup-validated configuration.
- 2 GB delivery path: with a local Bot API server the bot sends media by file path off a shared volume, so it never uploads the file over HTTP or holds it in memory.
- Persistent download queue with bounded concurrency; jobs are resumed after a restart.
- Repository-pattern data layer over SQLite with schema migrations.
Full documentation is available on the project site: zenonel.github.io/TelegramMediaRelayBot-Site
Or in docs/documentation/en/ inside the repo. Covers setup, installation, configuration, and usage.
Active development plans are tracked on the latest release page. Strategic direction:
- Plugin system with monetization-ready plugins for commercial use cases.
- (Under review) Mobile-side runtime for users who can't run servers.
- (Under consideration) Text formatting support, in-bot administrative functions.
- General improvements and fixes.
CHANGELOG.md: full history of changes.
The bot logs all actions to console; file logging is on the roadmap. Logging level is configurable via the settings file.
The project started from my girlfriend's complaints about manually downloading TikTok videos for me, since I don't use the platform myself. What began as a one-off automation grew into a full media-relay ecosystem: multi-user, multi-platform, plugin-extensible. The mission stayed simple: give people a self-hosted way to share content across platforms without surrendering their data to any single service.
This project is licensed under AGPL-3.0. See LICENSE for details.
If you have questions, suggestions, or found a bug, please open an issue.
The project is currently not accepting external contributions, but this may change in future. Stay tuned.
Copyright (C) 2024-2026 ZenonEl
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.