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.

---

🚀 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 <title>:

  • Searches Overseerr for movies or TV shows.
  • Returns a paginated list with buttons to request media or report issues.
  • Example: /check Breaking Bad

• /settings:

  • Opens the interactive Dashboard.
  • Users can: Log in/out (Email or Plex), manage their notification preferences.
  • Admins can: Change bot modes, manage users, toggle group mode.

Admin Features

All admin actions are performed via the Dashboard:

• Change Operation Mode: Switch between Normal, API, and Shared modes.
• User Management: Block/Unblock users, promote to Admin, or create new Overseerr users.
• System Notifications: Enable/Disable startup notifications ("System Online").

---

Smart Group Mode

Group Mode allows you to restrict the bot to a specific Telegram group or thread, making it perfect for shared servers.

How it works in v4.0.0:

1. Admin enables Group Mode in /settings.
2. Admin types /start in the group to link it.
3. New Users: When a user types /start in the group, the bot sends a button [🔐 Enter Password Privately].
4. The user authenticates in a private chat.
5. Once successful, the bot automatically notifies the group: "✅ User is now authorized!".

No need to disable Telegram's "Group Privacy Mode" via BotFather anymore!

---

FAQ

• How do I log in with Plex?
  Go to /settings -> Login. Select "▶️ Plex Account". The bot will provide a link to authorize the device.

• Why does the bot say "Status" instead of "1080p"?
  The bot detects your Overseerr configuration. If you don't have a separate 4K server configured, it neutrally labels the availability as "Status" to avoid confusion (since the file could be 4K even on a standard server).

• What if I forget the bot password?
  The password is set via the PASSWORD environment variable. Check your Docker or Config file.

• Why don't I see "Manage Notifications"?
  You must be logged in (Normal/Shared Mode) or have a user selected (API Mode) to configure notifications.

---

License

This project is licensed under the GPL-3.0 License. See the LICENSE file for details.

---

Contact

For issues or feature requests, open an issue on GitHub.

---

Built with ❤️ for media enthusiasts!