Telegram Files

A self-hosted Telegram file downloader for continuous, stable, and unattended downloads.

🔗 Table of Contents

• 📍 Overview
• 🧩 Screenshots
• 🚀 Getting Started
• ⌨️ Development
  • ☑️ Prerequisites
  • ⚙️ Installation
• 📌 Project Roadmap
• 🔰 Contributing
• 🎗 License
• 🆗 FAQs

📍 Overview

• Seamless file downloads from Telegram channels and groups
• Support for multiple Telegram accounts to manage and download files simultaneously
• Pause and resume downloads anytime, with automatic file transfer to designated destinations
• Instant preview of downloaded videos and images
• Fully responsive design with mobile-friendly access, Progressive Web App (PWA) support, and offline capabilities
• Easily fetch files from Telegram shared links

🧩 Screenshots

More Screenshots

🚀 Getting Started

Before getting started with telegram-files, you should apply a telegram api id and hash. You can apply for it on the Telegram API page.

Using docker  

docker run -d \
  --name telegram-files \
  --restart always \
  -e APP_ENV=${APP_ENV:-prod} \
  -e APP_ROOT=${APP_ROOT:-/app/data} \
  -e TELEGRAM_API_ID=${TELEGRAM_API_ID} \
  -e TELEGRAM_API_HASH=${TELEGRAM_API_HASH} \
  -p 6543:80 \
  -v ./data:/app/data \
  ghcr.io/jarvis2f/telegram-files:latest

Using docker-compose

Copy docker-compose.yaml and .env.example to your project directory and run the following command:

docker-compose up -d

Install on unRaid

On unRaid, install from the Community Repositories by searching for telegram-files.

Important Note: You should NOT expose the service to the public internet. Because the service is not secure.

⌨️ Development

☑️ Prerequisites

Before getting started with telegram-files, ensure your runtime environment meets the following requirements:

• Programming Language: JDK23,TypeScript
• Package Manager: Gradle,Npm
• Container Runtime: Docker

⚙️ Installation

Install telegram-files using one of the following methods:

Build from source:

1. Clone the telegram-files repository:

git clone https://github.com/jarvis2f/telegram-files

1. Navigate to the project directory:

cd telegram-files

1. Install the project dependencies:

Using npm  

cd web
npm install

Using gradle  

cd api
gradle build

Using docker  

docker build -t jarvis2f/telegram-files .

📌 Project Roadmap

• ✅ Task 1: Automatically download files based on set rules.
• ✅ Task 2: Download statistics and reports.
• ✅ Task 3: Improve Telegram’s login functionality.
• ✅ Task 4: Support auto transfer files to other destinations.
• ✅ Task 5: File table is optimized using virtual lists.
• ✅ Task 6: Preload file information to support responsible searches.

🔰 Contributing

• 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
• 🐛 Report Issues: Submit bugs found or log feature requests for the telegram-files project.
• 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.

🎗 License

This project is protected under the MIT License. For more details, refer to the LICENSE file.

🆗 FAQs

Q. Can't start the api server, error：java.lang.UnsatisfiedLinkError: no tdjni in java.library.path

A. Maybe download tdlib failed, you can see the entrypoint.sh file, then download tdlib manually.

Q. Web's spoiler is static, how to solve it?

A. 1. Because CSS Houdini Paint API is not supported by all browsers. 2. It is only supported on https.

Q. How to use the telegram-files maintenance tool?

A. You can use the following command to run the maintenance tool(before running the command, you should stop telegram-files container):

docker run --rm \
  --entrypoint tfm \
  -v $(pwd)/data:/app/data \
  -e APP_ROOT=${APP_ROOT:-/app/data} \
  -e TELEGRAM_API_ID=${TELEGRAM_API_ID} \
  -e TELEGRAM_API_HASH=${TELEGRAM_API_HASH} \
  ghcr.io/jarvis2f/telegram-files:latest ${Maintenance Command}