• Python 99.3%
  • Dockerfile 0.7%
Find a file
Alex Bukharov 4a063ed1c0
All checks were successful
ci/woodpecker/tag/build Pipeline was successful
Retries on connecting to Telegram API
2026-10-30 15:03:23 +11:00
.woodpecker Add woodpecker pipeline 2026-10-30 13:31:38 +11:00
.dockerignore Add woodpecker pipeline 2026-10-30 13:31:38 +11:00
.gitignore Add woodpecker pipeline 2026-10-30 13:31:38 +11:00
bot_settings.py Retries on connecting to Telegram API 2026-10-30 15:03:23 +11:00
config_template.py Major Update v4.0.0 2025-12-07 22:07:47 +01:00
docker-compose.yml Major Update v4.0.0 2025-12-07 22:07:47 +01:00
docker-compose_template.yml Major Update v4.0.0 2025-12-11 20:24:14 +01:00
Dockerfile Add woodpecker pipeline 2026-10-30 13:31:38 +11:00
main.py Retries on connecting to Telegram API 2026-10-30 15:03:23 +11:00
overseerr_api.py Allow to select seasons for tv shows 2026-10-30 14:58:21 +11:00
Patchnotes 4.0.0.txt Major Update v4.0.0 (#33) 2025-12-14 21:20:29 +01:00
README.md Revise README for Overseerr Telegram Bot v4.0.0 2025-12-14 21:10:07 +01:00
requirements.txt Major Update v4.0.0 2025-12-07 22:07:47 +01:00
utils.py Major Update v4.0.0 2025-12-14 20:10:01 +01:00

Overseerr Telegram Bot

The Overseerr Telegram Bot enables seamless interaction with your Overseerr instance through Telegram. Search for movies and TV shows, check availability, request new titles, report issues, and manage notifications—all from your Telegram chat.

With Version 4.0.0, the bot has been rebuilt for high performance (Async) and includes powerful features like Plex Authentication and Smart Group Chat Integration.

📚 Detailed Documentation: Explore the Wiki for comprehensive guides on setup, configuration, and advanced usage.

🐳 Docker Image: Pull the latest bot image from Docker Hub.


✨ Features

  • Media Search: Use /check <title> to find movies or TV shows (e.g., /check The Matrix) and view detailed results, including posters and availability.
  • Smart Availability: Instantly see if a title is available. Handles single-server setups gracefully by adjusting status labels automatically.
  • Title Requests: Request missing titles in HD (1080p) or 4K, respecting Overseerr user permissions for quality settings.
  • Authentication: Log in securely via Email/Password or your Plex Account (PIN Flow).
  • Issue Reporting: Report issues like video glitches, audio sync problems, or missing subtitles directly to Overseerr.
  • Notification Management: Customize Telegram notifications for Overseerr events (e.g., request approvals, media availability).
  • Admin Dashboard: A completely redesigned /settings menu allows admins to switch operation modes, manage users, and toggle system notifications.
  • Smart Group Mode: Use the bot safely in group chats.

Note

The language of media titles and descriptions matches the language setting configured in Overseerr (e.g., German titles if Overseerr is set to German), while the bot's interface remains in English.

1 Start


🚀 Installation

For detailed installation instructions, refer to the Wiki.

Quick Start (Docker Compose)

version: "3.9"
services:
  telegram-bot:
    image: chimpanzeesweetrolls/overseerrrequestviatelegrambot:latest
    container_name: overseerr-bot
    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"
    volumes:
      - ./data:/app/data
    restart: unless-stopped

Operation Modes

The bot supports three operation modes, configurable by the admin via /settings:

  • 🌟 Normal Mode (Default):

    • Users log in individually using their Overseerr Email or Plex Account.
    • Requests are tracked to the specific user's account.
    • Best for: Public bots or multi-user households.
  • 🔑 API Mode:

    • No login required. Users select an existing Overseerr user from a list.
    • Uses the Admin API key for all requests.
    • Best for: Personal bots or trusted groups where individual logins are too cumbersome.
  • 👥 Shared Mode:

    • The Admin logs in once (via Email or Plex).
    • All Telegram users share this single session.
    • Users cannot change settings.
    • Best for: Families sharing a single media server account.

Learn more about configuring modes in the Wiki.


Commands

User Commands

  • /start:

    • Initializes the bot and prompts for a password (if enabled).
    • Smart Auth: If run in a group, it provides a "🔐 Enter Password Privately" button to keep your password safe.
    • First Run: The first user to run /start automatically becomes the Admin.
  • /check