Telegram Bot for File Statistics

This is a Telegram bot that provides statistics about files sent by users. The bot can track the total size of files, the number of files, the number of streamable files (e.g., videos), and categorize files by their extensions.

• Telegram Bot for File Statistics
  • 💪🏻 Features
  • 🖼️ Preview
  • 🚀 Requirements
  • 🧩 Installation
  • 🪄 Usage
  • ⭐ Commands
  • 🗑️ Uninstall
  • 💻 Telegram Bot API Server
    • 💪🏻 Features
    • 📋 Prerequisites
    • 🏁 Start the Server
  • 🐳 Running with Docker
    • 📋 Prerequisites
    • 🏁 Start the Project
  • 📜 License
  • ✨ Contributing

💪🏻 Features

• Track total file size
• Track total download size
• Count the number of files
• Identify streamable files (e.g., videos)
• Categorize files by their extensions
• Commands to view statistics and reset data
• Localized, with support for some languages
• Dockerized for easy deployment

🖼️ Preview

🚀 Requirements

• Python 3.12+
• uv for dependency management

🧩 Installation

1. Clone the repository:

   git clone https://github.com/Francesco146/telegram-file-statistics-bot.git
   cd telegram-file-statistics-bot

2. Install uv if you haven't already:

   pip install uv

3. Create a new virtual environment using uv:

   uv venv

   and activate it:

   source .venv/bin/activate

4. Install the required packages using uv

   uv sync

5. Install the bot:

   uv run pip install .

6. Create a .env file in the root directory and add your Telegram bot token:

   TELEGRAM_TOKEN='your-telegram-bot-token'
   # For local server
   TELEGRAM_API_ID='your-telegram-api-id'
   TELEGRAM_API_HASH='your-telegram-api-hash'
   # Optional
   BOT_LANGUAGE='it'
   DEBUG_MODE='False'
   LOCAL_SERVER_MODE='False'
   DATABASE_FILE='file_statistics.db'

🪄 Usage

Run the bot:

telegram-file-statistics-bot [-h] [-t TOKEN] [-db DATABASE] [-d] [-v] [-l]

⭐ Commands

• /start: Show an home page
• /help: Show help message
• /stats: Show file statistics
• /reset: Reset file statistics

🗑️ Uninstall

To uninstall the bot, run:

uv run pip uninstall telegram-file-statistics-bot

💻 Telegram Bot API Server

This subsection sets up a local Telegram Bot API server to support bots using the official Telegram Bot API. Running a local instance adds support of archives for the main bot. This setup uses Docker to run the aiogram/telegram-bot-api image. The server will run locally on port 8081 by default and store its data in a dedicated volume.

💪🏻 Features

• Enables archives analysis for the main bot
• Dockerized
• Persistent data storage

📋 Prerequisites

• Docker and Docker Compose installed on your system
• A .env file in the root project directory containing your configuration (see below)

The .env file should be placed in the root directory. Add the following variables:

TELEGRAM_API_ID='your-telegram-api-id'
TELEGRAM_API_HASH='your-telegram-api-hash'

🏁 Start the Server

Run the following command to start the Telegram Bot API server:

docker compose up telegram-bot-api

🐳 Running with Docker

This project can be run using Docker and Docker Compose. The docker-compose.yml file defines two services: telegram-bot-api and telegram-bot. The former is the Telegram Bot API server, while the latter is the bot itself. The bot service is configurable only through environment variables in the .env file.

📋 Prerequisites

• Docker and Docker Compose installed on your system
• A .env file in the root project directory containing your configuration (see below)

The .env file should be placed in the root directory. For more information, see the Installation section.

🏁 Start the Project

Run the following command to start the entire project, including the Telegram Bot API server and the bot itself:

docker compose up

This command will start both the telegram-bot-api and telegram-bot services defined in the docker-compose.yml file. The bot will be accessible and ready to process files and provide statistics.

If you want to run the bot only, you can use the following command:

docker compose up telegram-bot

Note that, if changes are made to the bot, the image must be rebuilt using the --build flag:

docker compose up --build

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

✨ Contributing

Contributions and translations are welcome! Please open an issue or submit a pull request for any changes. For more information, see the CONTRIBUTING file.