I recently wanted a way to get notified in Telegram every time a torrent finished downloading on my server. Since I’m running qBittorrent in Docker on OpenMediaVault, the usual desktop notification solutions were out of the question. Instead, I integrated Telegram using a simple bash script and qBittorrent's built-in “Run external program” feature.

Here’s how I set it up.

🧱 Requirements

  • qBittorrent running in Docker (I use it via Portainer)
  • A Telegram bot (takes 2 minutes to create)
  • A Telegram group where the bot has permission to post
  • A shared volume between your host and qBittorrent container (to run a script)

🤖 Step 1: Create a Telegram Bot

  1. Open Telegram and search for @BotFather
  2. Send /start and then /newbot
  3. Give your bot a name and a username (it must end in bot, like TorrentAlertBot)

Copy the bot token BotFather gives you — it looks like:

123456789:ABCdefGhIjKlMnOpQRStUvWxYZ1234567890

🧑‍💻 Step 2: Create a Notification Script

On your host (not inside the container), create this bash script:

#!/bin/bash

TORRENT_NAME="$1"
TORRENT_PATH="$2"
TORRENT_CATEGORY="$3"

BOT_TOKEN="REPLACE_WITH_YOUR_TOKEN"
CHAT_ID="-111223344"  # Replace with your group ID or chat ID

MESSAGE="✅ Torrent finished: *$TORRENT_NAME*%0A📂 Path: \`$TORRENT_PATH\`%0A🏷 Category: *$TORRENT_CATEGORY*"

curl -s -X POST "https://api.telegram.org/bot$BOT_TOKEN/sendMessage" \
    -d "chat_id=$CHAT_ID&text=$MESSAGE&parse_mode=Markdown"

Save it to:

/srv/dev-disk-by-uuid-901ed917-d6c3-03fe-9bfb-9cb6c8101a4a/scripts/qbt_notify_telegram.sh

Make it executable:

chmod +x /srv/.../scripts/qbt_notify_telegram.sh

📦 Step 3: Mount the Script into Your qBittorrent Container

If you're using Portainer:

  • Edit the container
  • Add a volume:
    • Host: /srv/.../scripts
    • Container: /scripts
  • Redeploy the container

⚙️ Step 4: Configure qBittorrent

Go to:

Tools → Options → Downloads → Run external program on torrent finished

Paste:

/scripts/qbt_notify_telegram.sh "%N" "%D" "%L"

Make sure:

  • %N = Torrent name
  • %D = Save path
  • %L = Category (not %C! %C is number of files)

✅ Done!

Now every time a torrent completes, you’ll get a Telegram message like this:

✅ Torrent finished: Terminator. Collection
📂 Path: /downloads/movies
🏷 Category: Movies

🧠 Pro Tips

  • You can add filtering logic in the script if you only want messages for certain categories.
  • Combine this with tag-based automation for even more control.