TrackyBot

TrackyBot is a self-hosted Telegram bot that helps you manage a personal list of movies, TV series, video games, and anime. It lets you easily keep track of what you’ve already watched or played and what you want to watch or play in the future.

Features

• Find specific movies, series, games, or anime to add to your personal list
• Set the status of each title as Watched, Watching, or To Watch
• Search through your saved titles
• Get insights on the number of titles in each category and status
• Export your personal lists

demo.mp4

This bot is developed using:

• Python
• python-telegram-bot (library for Telegram bot functionality)
• TinyDb (lightweight JSON-based database)

TrackyBot uses public APIs to fetch title information from:

• Movies & TV Series: OMDb API
• Video Games: RAWG API
• Anime: AniList API

Installation

1. Clone the repository
2. Go to project folder
3. Create a Python virtual environment

python3 -m venv venv

4. Activate the virtual environment

source venv/bin/activate

5. Install the dependencies

pip3 install -r requirements.txt

6. Rename the file template.env in .env. In this file you need to insert 4 things:

   • Telegram Bot Token (TOKEN): you can create one using BotFather)
   • OMDb API Key (MOVIE_SERIES_KEY): you can retreive one for free from OMDb)
   • RAWG API Key (GAME_KEY): you can retreive one for free from RAWG)
   • Your Telegram user ID (USER_ID): If you don't know, leave it blank; the bot will print your ID on the first Telegram message. Once you obtain it, remember to enter it here.

7. Run the bot

python3 bot.py

Autostart with cron

You can configure your system to automatically start the bot on boot using cron.

Open the crontab editor

crontab -e

Add the following line at the bottom, replacing "<path_to_project>" with the absolute path of the project

@reboot /bin/bash -c 'cd <path_to_project> && source venv/bin/activate && python3 bot.py >> bot.log 2>&1'

Save and exit the crontab editor

Usage

The bot supports only two text commands:

• /start: starts a conversation with the bot
• /cancel: interrupts any ongoing operation

To begin, simply type /start. The bot will present you with a list of available actions:

• Add: Allows you to search for a title and add it to your list
• Inspect lists: lets you view and manage all your saved titles
• Search saved lists: search for a specific title among your saved entries
• Export data: export your lists in two formats:
  • Plain text: a single, human-readable file containing all titles
  • JSON: The actual data files used internally by the bot (one for each media type). You can import them into a new bot installation by placing the files in the data/ folder
• Show stats: Displays statistics such as the total number of saved titles
• Exit: Ends the conversation

Note: If the bot prompts you with your user ID, it means you haven't added it to the .env file yet. Add it now and restart the bot.

You can type /cancel at any time to cancel the current operation, then restart with /start.