Send Torrent Telegram Bot 🤖

A simple and secure Telegram bot that receives .torrent files and saves them to a shared folder monitored by your torrent client (qBittorrent, Transmission, etc.).

Perfect for managing your torrents remotely through Telegram!

✨ Features

• 🔒 Secure: Only authorized chat IDs can send torrents
• 👨‍👩‍👧‍👦 Multi-user: Support for multiple family members (comma-separated chat IDs)
• 📡 Multi-RSS: Up to 10 RSS feeds per user with custom names
• 🐳 Dockerized: Easy deployment with Docker Compose
• 🔄 Auto-update: Automatic Docker image builds on GitHub push
• 📦 Lightweight: Minimal Python dependencies
• 🚀 Fast: Instant torrent file transfer to your download manager
• 🔍 Logging: Complete activity logging for monitoring
• 🎨 Visual UI: Beautiful interface with inline menus and buttons

📋 Prerequisites

• Docker and Docker Compose installed on your server
• A Telegram Bot Token (Get one from @BotFather)
• A torrent client (qBittorrent, Transmission, etc.) with a watch folder configured

🚀 Quick Start

1. Get Your Telegram Chat ID

1. Start a conversation with @userinfobot on Telegram
2. It will reply with your Chat ID (a number like 123456789)
3. Save this number for the next step

2. Clone the Repository

git clone https://github.com/artcc/send-torrent-telegram-bot.git
cd send-torrent-telegram-bot

3. Configure Environment Variables

Create a .env file from the example:

cp .env.example .env

Edit the .env file with your values:

# Get your bot token from @BotFather on Telegram
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

# Your Telegram Chat ID(s) - comma separated for multiple users
ALLOWED_CHAT_IDS=123456789,987654321

# Path to your torrent client's watch folder
TORRENT_WATCH_PATH=/path/to/qbittorrent/watch

# Path on your host system for RSS data persistence
RSS_DATA_PATH=./data

# Path to RSS storage file inside the container
RSS_STORAGE_FILE=/data/rss_urls.json

4. Deploy with Docker Compose

docker-compose up -d

5. Verify the Bot is Running

docker logs send-torrent-telegram-bot

You should see: Bot is running...

💬 Using the Bot

Basic Usage

1. Open Telegram and find your bot
2. Send /start to verify your chat ID and authorization
3. Send any .torrent file to the bot
4. The bot will save it to your watch folder
5. Your torrent client will automatically pick it up!

RSS Feed Integration

The bot can browse your private tracker RSS feeds and download torrents directly. You can add up to 10 RSS feeds per user!

1. Add your RSS feeds:

   /setrss https://your-tracker.com/rss/key1 MyTracker
   /setrss https://another-tracker.com/rss/key2 AnotherOne
   

   ⚠️ Name cannot contain spaces. If you add a feed with an existing name, it will be overwritten.

2. Browse your feeds:

   • Use /browse command, or
   • Click "📡 Browse RSS Feed" button from the main menu
   • If you have multiple feeds, you'll see buttons to select which one to browse
   • If you have only one feed, it opens directly

3. Select torrents:

   • Click on torrent titles to select (☐) or deselect (✅)
   • Select multiple torrents at once
   • See the counter showing how many are selected

4. Download selected torrents:

   • Click "⬇️ Download (N)" button to download all selected torrents
   • The bot will download them all and show a complete summary

5. Manage your feeds:

   /clearrss
   

   • Shows all your feeds with delete buttons
   • Confirmation required before deleting

Features:

• 📡 Up to 10 RSS feeds per user
• ✅ Multi-selection with visual checkboxes
• 📺 Category-based emojis (Series, Movies, Others)
• 📊 Real-time selection counter
• 📝 Complete summary after downloading
• 🔄 Overwrite feeds by using same name

Note: Your RSS URLs are stored securely per user and include your personal RSS key from your tracker.

Available Commands

• /start - Show welcome message and main menu
• /help - Show help information and all commands
• /status - Check bot status and authorization
• /menu - Show interactive menu with buttons
• /chatid - Show your Chat ID
• /author - About the author
• /setrss <URL> <name> - Add RSS feed with custom name (max 10)
• /browse - Browse and download from your RSS feeds
• /clearrss - Manage and delete your RSS feeds

🔧 Integration with Torrent Clients

qBittorrent

1. In qBittorrent settings, enable "Automatically add torrents from"
2. Set the path to match your TORRENT_WATCH_PATH
3. (Optional) Enable "Delete .torrent files afterwards"

Example docker-compose for qBittorrent:

version: '3.8'

services:
  qbittorrent:
    image: linuxserver/qbittorrent:latest
    container_name: qbittorrent
    volumes:
      - ./config:/config
      - ./downloads:/downloads
      - ./watch:/watch  # Same path as bot
    ports:
      - "8080:8080"
    restart: unless-stopped

  send-torrent-telegram-bot:
    image: ghcr.io/artcc/send-torrent-telegram-bot:latest
    container_name: send-torrent-telegram-bot
    env_file:
      - .env
    volumes:
      - ./watch:/watch  # Shared folder for torrents
      - ./data:/data    # RSS data persistence
    restart: unless-stopped

📦 Installing via Portainer

1. Go to your Portainer instance
2. Navigate to Stacks → Add Stack
3. Name it: send-torrent-telegram-bot
4. Paste the contents of docker-compose.yml
5. Add your environment variables in the "Environment variables" section
6. Click Deploy the stack

🔄 Auto-Updates

Every push to the main branch automatically:

1. Builds a new Docker image
2. Publishes it to GitHub Container Registry
3. Tags it as latest

To update your running bot:

docker-compose pull
docker-compose up -d

Or in Portainer: Click on your stack → Pull and redeploy

🛡️ Security Notes

• Never commit your .env file - it contains sensitive tokens
• Your bot token gives full control of your bot - keep it secret
• Only share your chat ID with trusted users
• The bot only accepts .torrent files from authorized chat IDs
• All unauthorized access attempts are logged

📝 Architecture

┌─────────────────┐
│  Telegram User  │
└────────┬────────┘
         │ .torrent file OR RSS browse
         ▼
┌─────────────────────┐
│  Telegram Bot API   │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│  Python Bot         │
│  (Docker Container) │
│  - RSS Parser       │
│  - File Handler     │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│  Shared Volumes     │
│  - /watch (torrents)│
│  - /data (RSS URLs) │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│  Torrent Client     │
│  (qBittorrent, etc) │
└─────────────────────┘

🐛 Troubleshooting

Bot doesn't respond

• Check if the container is running: docker ps
• Check logs: docker logs send-torrent-telegram-bot
• Verify your bot token is correct
• Ensure the bot is not rate-limited by Telegram

"Unauthorized" message

• Verify your chat ID is correct in .env
• Use /start command to see your actual chat ID
• Check for spaces in the ALLOWED_CHAT_IDS variable

Torrents not being picked up by client

• Verify the watch folder path is correct on both sides
• Check folder permissions: ls -la /path/to/watch
• Ensure your torrent client is monitoring the folder
• Check torrent client logs

Permission denied errors

sudo chown -R 1000:1000 /path/to/watch
sudo chmod -R 775 /path/to/watch

RSS feed issues

• Empty feed: Verify your RSS URL includes your personal key
• Invalid feed: Check if the tracker is accessible from your server
• Torrents not downloading: Ensure the RSS feed provides direct .torrent links
• RSS data lost after restart: Verify RSS_DATA_PATH volume is mounted correctly
• Cannot add more feeds: Limit is 10 feeds per user. Use /clearrss to remove unused ones
• Feed not updating: The name cannot contain spaces, use /setrss <URL> <name> format

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🎨 Bot Icon

Want to set a custom icon for your bot in Telegram? Download the high-resolution icon and send it to @BotFather using the /setuserpic command.

🙏 Acknowledgments

• python-telegram-bot - Excellent Telegram Bot API wrapper
• The open-source community for inspiration and tools

📧 Support

If you encounter any issues or have questions:

1. Check the Troubleshooting section
2. Search existing GitHub Issues
3. Open a new issue with detailed information

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

_{100% built with GitHub Copilot (Claude Sonnet 4.5)
Arturo Carretero Calvo — 2026}