Overseerr Telegram Bot

A phyton script to request media via a Telegram bot via Overseerr

The Overseerr Telegram Bot bridges your Telegram account with Overseerr, enabling you to request movies and TV shows directly within Telegram.

🌟 Features

• 🔍 Simple Search - Quickly search for movies and series
• 📥 Easy Requests - Submit media requests with just a few taps
• 🛠 Issue Reporting - Report any issues or problems
• 📊 Check Availability – See if a movie or show is already in your library, pending approval, or being processed
• 🔔 Get Notified – Get notification updates for your requests
• 👥 User Management - Multi-user support to share the bot with friends
• 👌 User-Friendly - Intuitive and easy to use, ensuring a seamless media management experience
• 🔒 Access Control – Set up a password to restrict access

How to use

1. Open a chat with your Telegram bot
2. /start
3. /check MOVIE / TV-Show

Note

The language of the media titles and descriptions will match the language setting configured in Overseerr.

Update on Ubuntu / Linux

cd OverseerrRequestViaTelegramBot
git pull

Installation

Create a Telegram Bot

Follow the instructions at Telegram Bots: How do I create a bot? to create a new Telegram bot. After creating the bot, you'll receive a bot token. Keep this token secure, as it will be needed later.

get overseerr API_KEY

Obtain your Overseerr API key from your Overseerr instance settings.

Installation on Ubuntu / Linux (without Docker)

Note

If you prefer to install using Docker, please refer to the section Installation with Docker.

---

1. Prerequisites

Ensure the following are installed on your system:

• Python 3.12.x or newer
• pip (Python's package manager)
• git (for cloning the repository)

Install them using the following commands:

sudo apt update
sudo apt install python3 python3-pip git

---

2. Download and Set Up the Bot

1. Clone the repository and navigate to the bot's directory:

   git clone https://github.com/LetsGoDude/OverseerrRequestViaTelegramBot.git
   cd OverseerrRequestViaTelegramBot

2. Ensure you have all required Python dependencies installed. They are listed in requirements.txt. Install them using:

   pip install -r requirements.txt

---

3. Configure the Bot

Rename the configuration template and update it with your actual values:

mv config_template.py config.py
nano config.py

# config.py

OVERSEERR_API_URL = 'http://YOUR_IP_ADDRESS:5055/api/v1' # Replace with your Overseerr URL
OVERSEERR_API_KEY = 'YOUR_OVERSEERR_API_KEY'             # Replace with your API key
TELEGRAM_TOKEN = 'YOUR_TELEGRAM_TOKEN'                   # Replace with your Telegram bot token

# Access Control Configuration (Optional)
# Set a password to protect access. If empty, no access control is applied.
PASSWORD = "your-secure-password"  # or "" for no access control

---

4. Run the Bot Manually (Optional)

To verify that everything works correctly, you can run the bot manually:

python3 telegram_overseerr_bot.py

---

5. Run the Bot as a Service (Recommended)

To ensure the bot starts automatically at boot, create a systemd service:

1. Open a new service file:

   sudo nano /etc/systemd/system/telegram_bot.service

2. Add the following configuration (replace paths and username as needed):

   [Unit]
   Description=Overseerr Telegram Bot
   After=network.target
   
   [Service]
   Type=simple
   ExecStartPre=/bin/sleep 10
   ExecStart=/usr/bin/python3 /path/to/your/script.py   #e.g. /home/USERNAME/OverseerrRequestViaTelegramBot/telegram_overseerr_bot.py
   WorkingDirectory=/path/to/your/script-directory      #e.g. /home/USERNAME/OverseerrRequestViaTelegramBot
   Restart=always
   User=your-username
   Environment=PYTHONUNBUFFERED=1
   
   [Install]
   WantedBy=multi-user.target
   

3. Save and exit the file (Ctrl+O, Enter, Ctrl+X).

4. Reload systemd to apply changes, Enable and start the service

   sudo systemctl daemon-reload
   sudo systemctl enable telegram_bot.service
   sudo systemctl start telegram_bot.service
   

5. Check the service status to ensure it’s running:

   sudo systemctl status telegram_bot.service

Installation with Docker

Our Docker Hub

docker-compose.yml

version: "3.9" # Specifies the version of the Docker Compose file format
services:
  telegram-bot: # The name of the service (container)
	image: chimpanzeesweetrolls/overseerrrequestviatelegrambot:latest
	environment:
	  OVERSEERR_API_URL: "http://your-overseerr-ip:5055/api/v1"
	  OVERSEERR_API_KEY: "your_overseerr_api_key"
	  TELEGRAM_TOKEN: "your_telegram_token"
	  PASSWORD: "your_password" # or "" for no access control
	volumes:
	  - ./data:/app/data
	restart: unless-stopped

Without compose:

docker run -d \
    --name telegram-bot \
    -v $(pwd)/data:/app/data \ 
    -e OVERSEERR_API_URL="http://your-overseerr-ip:5055/api/v1" \ 
    -e OVERSEERR_API_KEY="your_overseerr_api_key" \ 
    -e TELEGRAM_TOKEN="your_telegram_token" \ 
    -e PASSWORD="your_password" \
    chimpanzeesweetrolls/overseerrrequestviatelegrambot:latest

NAS GUI (QNAP as an example, other manufacturers should be similar)