🚀 KPS - File To Link Bot ⚡

🚀 High-Performance Telegram File-to-Link Bot ⚡ For Direct Links 🎬 Streaming

---

📑 Table of Contents

• About The Project
• How It Works
• Features
• Getting Started
  • Prerequisites
  • Installation
• Configuration
  • Essential Configuration
  • Optional Configuration
• Usage and Commands
  • Basic Usage
  • Commands Reference
• Advanced Feature Setup
  • Token System
  • URL Shortening
  • Rate Limiting System
• Production Deployment Guide
  • Custom Domain & FQDN System
  • Reverse Proxy Setup
• Support & Community
  • Troubleshooting & FAQ
  • Contributing
• License
• Acknowledgments

---

About The Project

KPS Bots is a powerful Telegram bot that transforms Telegram files into high-speed direct links, perfect for both streaming and rapid downloading. Share files via HTTP(S) links without needing to download them from the Telegram client first.

💡 Perfect For

• 🚀 Bypassing Telegram's built-in download speed limits
• ☁️ Unlimited cloud storage with fast streaming and download links
• 🎬 Content creators sharing media files
• 👥 Communities distributing resources
• 🎓 Educational platforms sharing materials

How It Works

User Uploads File → Telegram Bot → Forwards to Channel → Generates Direct Link → Direct Download / Streaming

1. Upload → User sends any file to the bot.
2. Store → The bot forwards the file to your private storage channel (BIN_CHANNEL), where it is permanently saved to generate the link.
3. Generate → A unique, permanent link is created.
4. Stream/Download → Anyone with the link can stream or download the file directly in their browser.
5. Balance → Multi-client support distributes the load for high availability.

Features

Core Functionality

• ✅ Direct Link Generation - Convert any Telegram file into a direct HTTP(S) link.
• ✅ Permanent Links - Links remain active as long as the file exists in the storage channel.
• ✅ Browser Streaming & Downloading - Stream media directly or download files at high speed without a Telegram client.
• ✅ All File Types - Supports video, audio, documents, images, and any other file format.
• ✅ Batch Processing - Generate links for multiple files at once with a single command.

Performance & Scalability

• ✅ Multi-Client Support - Distributes traffic across multiple Telegram bots to avoid limits and increase throughput.
• ✅ Async Architecture - Built with aiohttp and asyncio for non-blocking, high-performance operations.
• ✅ MongoDB Integration - Ensures persistent and reliable data storage.

Security & Control

• 🔐 Token Authentication - Secure user access with a time-limited token system.
• 🛡️ Admin Controls - Full suite of commands for user and bot management.
• 👤 User Authentication - Require users to join a specific channel before they can use the bot.
• ✅ Channel/Group Support - Fully functional in private chats, groups, and channels.

Customization

• 🌍 Custom Domain - Serve files from your own domain for a professional look.
• 🔗 URL Shortening - Integrate with URL shortener services for clean, shareable links.
• 🎨 Custom Templates - Personalize messages sent by the bot to match your brand.
• 📈 Media Info Display - Shows file size, duration, and format details in the response message.

Getting Started

This section covers the system requirements and step-by-step installation guide for setting up KPS Bots.

Prerequisites

Requirement	Description	Source
Python 3.13	Programming language	python.org
MongoDB	Database	mongodb.com
Telegram API	API credentials	my.telegram.org
Bot Token	From @BotFather	@BotFather
Public Server	VPS/Dedicated server	Any provider
Storage Channel	For file storage	Create in Telegram

Installation

🚀 Deployment Guide (VPS)

1. Installing Requirements

Clone this repository:

git clone https://github.com/Tamilupdates/FileToLink f2l && cd f2l

Setting up config file:

cp config_sample.env config.env

Edit your settings:

nano config.env

Fill up rest of the fields. Meaning of each field is discussed below.

NOTE: All values must be filled between quotes, even if it's Int, Bool or List.

---

2. Build and Run the Docker Image

Make sure you mount the app folder and install Docker following the official documentation.

There are two methods to build and run the Docker image:

2.1 Using Official Docker Commands

• Start Docker daemon (skip if already running):

  sudo dockerd

• Build the Docker image:

  sudo docker build . -t kps

• Run the image:

  sudo docker run --name kps -p 80:80 -p 8080:8080 kps

• To stop the running image:

  First, list running containers:

  sudo docker ps

  Then, stop the container using its ID:

  sudo docker stop <container_id>

---

2.2 Using docker-compose (Recommended)

Note: If you want to use ports other than 80 and 8080 for torrent file selection and rclone serve respectively, update them in docker-compose.yml.

• Install docker-compose:

  sudo apt install docker-compose

• Build and run the Docker image (or view the current running image):

  sudo docker-compose up

• After editing files (e.g., using nano to edit start.sh), rebuild:

  sudo docker-compose up --build

• To stop the running image:

  sudo docker-compose stop

• To restart the image:

  sudo docker-compose start

• To view the latest logs from the running container (after mounting the folder):

  sudo docker-compose up

• Tutorial Video for docker-compose and checking ports:

  

---

Docker Notes

IMPORTANT NOTES:

1. You should stop the running image before deleting the container and you should delete the container before the image.
2. To delete the container (this will not affect on the image):

sudo docker container prune

3. To delete te images:

sudo docker image prune -a

3. Manual Installation

• Clone repository

git clone https://github.com/Tamilupdates/FileToLink f2l
cd f2l

• Setup virtual environment

python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

• Install dependencies

pip install -r requirements.txt

• Configure

cp config_sample.env config.env
nano config.env

• Run bot

python -m KPS

Tip: Start with the essential configuration to get KPS running, then add optional features as needed.

Configuration

Copy config_sample.env to config.env and fill in your values.

Essential Configuration

Variable	Description	Example
API_ID	Telegram API ID	12345678
API_HASH	Telegram API Hash	abc123def456
BOT_TOKEN	Bot token from @BotFather	123456:ABCdefGHI
BIN_CHANNEL	Storage channel ID	-1001234567890
OWNER_ID	Owner user ID	12345678
OWNER_USERNAME	Owner username	yourusername
DATABASE_URL	MongoDB connection	mongodb+srv://...
FQDN	Domain/IP address	f2l.kpsbots.com
HAS_SSL	HTTPS enabled	True or False
PORT	Server port	8080
NO_PORT	Hide port in URLs	True or False

Optional Configuration

Variable	Description	Default
MULTI_TOKEN1	Additional bot token 1 (use MULTI_TOKEN1, MULTI_TOKEN2, etc.)	(empty)
FORCE_CHANNEL_ID	Required channel join	(empty)
MAX_BATCH_FILES	Maximum files in batch processing	50
CHANNEL	Allow processing messages from channels	False
BANNED_CHANNELS	Blocked channel IDs	(empty)
SLEEP_THRESHOLD	Client switch threshold	300
WORKERS	Async workers	8
NAME	Bot name	KPSF2L
BIND_ADDRESS	Bind address	0.0.0.0
PING_INTERVAL	Ping interval (seconds)	840
TOKEN_ENABLED	Enable tokens	False
SHORTEN_ENABLED	URL shortening for tokens	False
SHORTEN_MEDIA_LINKS	URL shortening for media	False
TOKEN_TTL_HOURS	Token validity duration in hours	24
URL_SHORTENER_API_KEY	Shortener API key	(empty)
URL_SHORTENER_SITE	Shortener service	(empty)
SET_COMMANDS	Auto-set bot commands	True
RATE_LIMIT_ENABLED	Enable rate limiting	False
MAX_FILES_PER_PERIOD	Files per window	2
RATE_LIMIT_PERIOD_MINUTES	Time window	1
MAX_QUEUE_SIZE	Queue size	100
GLOBAL_RATE_LIMIT	Global limiting	True
MAX_GLOBAL_REQUESTS_PER_MINUTE	Global limit	4

Usage and Commands

Basic Usage

1. Start → Send /start to the bot.
2. Authenticate → Join required channels (if configured).
3. Upload → Send any media file.
4. Receive → Get a direct streaming and download link.
5. Share → Anyone can access the file via the link.

Commands Reference

User Commands

Command	Description
/start	Start the bot and get a welcome message. Also used for token activation.
/link	Generates a link. For batches, reply to the first file of a group and specify the count. Example: /link 5 will process that file and the next four.
/dc	Get the data center (DC) of a user or file. Use /dc id, or reply to a file or user.
/ping	Check if the bot is online and measure response time.
/about	Get information about the bot.
/help	Show help and usage instructions.

Admin Commands

Command	Description
/status	Check bot status, uptime, and resource usage.
/broadcast	Send a message to all users (supports text, media, buttons).
/stats	View usage statistics and analytics.
/ban	Ban a user or channel (reply to message or use user/channel ID).
/unban	Unban a user or channel.
/log	Send bot logs.
/restart	Restart the bot.
/shell	Execute a shell command.
/speedtest	Run network speed test and display comprehensive results.
/users	Show total number of users.
/authorize	Permanently authorize a user to use the bot (bypasses token system).
/deauthorize	Remove permanent authorization from a user.
/listauth	List all permanently authorized users.

BotFather Commands Setup

start - Initialize bot
link - Generate direct link
dc - Get data center info
ping - Check bot status
about - Bot information
help - Show help guide
status - [Admin] System status
stats - [Admin] Usage statistics
broadcast - [Admin] Message all users
ban - [Admin] Ban user
unban - [Admin] Unban user
users - [Admin] User count
authorize - [Admin] Grant access
deauthorize - [Admin] Revoke access
listauth - [Admin] List authorized
log - [Admin] Send bot logs
restart - [Admin] Restart the bot
shell - [Admin] Execute shell command
speedtest - [Admin] Run network speed test

Advanced Feature Setup

Token System

Enable controlled access with tokens:

1. Set TOKEN_ENABLED=True in your config.env.
2. Users receive automatic tokens on first use.
3. Admins can grant permanent authorization with /authorize to bypass tokens.
4. Tokens include activation links for secure access.

URL Shortening

Configure URL shortening for cleaner links:

SHORTEN_ENABLED=True
SHORTEN_MEDIA_LINKS=True
URL_SHORTENER_API_KEY=your_api_key
URL_SHORTENER_SITE=shortener.example.com

Rate Limiting System

KPS Bots implements a sophisticated multi-tier rate limiting system designed for high-performance file sharing:

Priority Queue Architecture

• Owner Priority: Complete bypass of all rate limits.
• Authorized Users: Dedicated priority queue with faster processing.
• Regular Users: Standard queue with fair scheduling.

Multi-Level Rate Limiting

• Per-User Limits: Configurable files per time window.
• Global Limits: System-wide request throttling.
• Sliding Window: Time-based rate limiting with automatic cleanup.

Smart Queue Management

• Automatic Re-queuing: Failed requests due to rate limits are intelligently re-queued.
• Queue Size Limits: Configurable maximum queue size.
• Flood Protection: Built-in protection against Telegram flood waits.

Network Speed Testing

Monitor server performance with built-in speed testing:

/speedtest

Features include download/upload speeds, latency measurements, and shareable result images for performance monitoring.

Production Deployment Guide

Custom Domain & FQDN System

KPS Bots provides enterprise-grade domain configuration through the FQDN setting, enabling professional file sharing with custom domains and comprehensive SSL support.

• Custom Domain Support: Set your primary domain for file sharing.
• Protocol Selection: Dynamically serves over HTTP/HTTPS based on your HAS_SSL configuration.
• Cloudflare Compatible: Full support for Cloudflare Origin Certificates and reverse proxies.
• Security Headers: Adds proper security headers for production deployments.

Reverse Proxy Setup

This guide will help you set up a secure reverse proxy using NGINX for your file streaming bot with Cloudflare SSL protection.

---

✅ What You Need

• A VPS or server running Ubuntu/Debian with NGINX installed.
• Your file streaming bot running on a local port (e.g., 8080).
• A subdomain (e.g., f2l.kpsbots.com) set up in Cloudflare.
• Cloudflare Origin Certificate files: cert.pem and key.key.

---

🔐 Step 1: Configure Cloudflare

• DNS: Add an A record for your subdomain pointing to your server's IP. Ensure Proxy Status is Proxied (orange cloud).
• SSL: In the SSL/TLS tab, set the encryption mode to Full (strict).

---

🛡️ Step 2: Set Up SSL Certificates on Server

Create a folder for your certificates and place cert.pem and key.key inside. Secure the private key.

sudo mkdir -p /etc/ssl/cloudflare/f2l.kpsbots.com
# Move/copy your cert.pem and key.key files into this directory
sudo chmod 600 /etc/ssl/cloudflare/f2l.kpsbots.com/key.key
sudo chmod 644 /etc/ssl/cloudflare/f2l.kpsbots.com/cert.pem

---

🛠️ Step 3: Create NGINX Configuration

Create a new file at /etc/nginx/sites-available/f2l.kpsbots.conf and paste the following, replacing f2l.kpsbots.com and 8080 with your values.

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name f2l.kpsbots.com;

    # SSL Configuration
    ssl_certificate     /etc/ssl/cloudflare/f2l.kpsbots.com/cert.pem;
    ssl_certificate_key /etc/ssl/cloudflare/f2l.kpsbots.com/key.key;

    # Basic security
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;

    location / {
        # Forward requests to your bot
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Settings for file streaming
        proxy_buffering off;
        proxy_request_buffering off;
        client_max_body_size 0;
    }
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name f2l.kpsbots.com;
    return 301 https://$host$request_uri;
}

---

🔄 Step 4: Test and Apply Changes

Enable the configuration, test it, and reload NGINX.

sudo ln -s /etc/nginx/sites-available/f2l.kpsbots.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Your reverse proxy is now securely streaming files behind Cloudflare!

Support & Community

Troubleshooting & FAQ

Bot not responding?

• Check if the BOT_TOKEN is correct in your config.env.
• Ensure your server's firewall is not blocking the bot's port.
• View bot logs for any error messages.

Links not working?

• Verify your FQDN and PORT settings are correct.
• If using SSL (HAS_SSL=True), ensure your reverse proxy and certificates are set up correctly.
• Check that the bot has admin rights in the BIN_CHANNEL and can forward messages there.

Q: How do I get my API credentials? A: Visit my.telegram.org/apps to get your API_ID and API_HASH.

Q: Where can I create a bot token? A: Use @BotFather on Telegram to create and manage your bot.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

License

Licensed under the Apache License 2.0. See the LICENSE file for details.

Acknowledgments

• Pyrofork - Telegram MTProto API Framework
• aiohttp - Asynchronous HTTP Client/Server
• Motor - Asynchronous MongoDB Driver
• TgCrypto - High-performance cryptography library

⚠️ Disclaimer

This project is not affiliated with Telegram. Use it responsibly and in compliance with Telegram's Terms of Service and all applicable local regulations.

---

⭐ Star this project if you find it useful!
Report Bug • Request Feature