A powerful, open-source, and feature-rich Telegram bot designed to rename, customize, and transform files effortlessly with support for custom thumbnails, metadata, captions, and video conversion.

⚡ Fast • 📝 Flexible • 🖼️ Customizable

📑 Table of Contents

• 🌸 Overview
• 📜 Architecture
• 📝 Tech Stack
• ✨ Features
• 🎥 Quick Start
• ⚙️ Configuration
• 🤖 Commands
• 🚀 Deployment
• 🤝 Contributing
• 📄 License
• 💬 Updates & Support
• 🙌 Credits
• 👨‍💻 Connect With Me

---

🌸 Overview

Rename Bot is a powerful Telegram file management bot that goes far beyond simple renaming. It combines 4GB file support, premium plans, thumbnails, metadata, captions, and file conversion into one convenient Telegram-based workflow.

💡 Take full control of your files with powerful customization tools.

🤔 Why Choose This Project?

• ⚡ Fast & Powerful — Process and rename files quickly with support for large files.
• 🎨 Highly Flexible — Customize your files with powerful options tailored to your needs.
• 💎 Premium Ready — Built-in plans and premium features for enhanced capabilities.
• 🚀 Easy to Deploy — Ready for self-hosting across multiple popular platforms.

🔄 How It Works

1. 📤 Send Your File — Upload the file you want to rename or process.
2. ⚙️ Choose Your Options — Configure your filename and preferred customization settings.
3. 🔄 Let the Bot Process — The bot applies your selected settings automatically.
4. 📥 Get the Result — Receive your customized file back through Telegram.

---

📜 Architecture

Runtime overview

flowchart TB
    subgraph TG["Telegram"]
        U["👤 User"]
        API["☁️ Telegram API<br/>(MTProto)"]
        CH["📢 Channels<br/>BIN / LOG / FSUB"]
    end
    subgraph PROC["bot.py — one process"]
        MAIN["🤖 TechifyBots client<br/>bot token · workers=200 · 50 xmit"]
        USER["👤 app client (file_rename)<br/>STRING_SESSION · 4GB uploads"]
        WEB["🌐 aiohttp web server<br/>:$PORT → welcome.html"]
        MW["🛡️ middleware chain<br/>maintenance → fsub → user-mw"]
        FEAT["⚙️ feature plugins<br/>rename · admin · plans · metadata"]
    end
    subgraph DATA["MongoDB — Rename_Bot"]
        CDB[("👥 user<br/>profile + quota")]
        PDB[("💎 premium<br/>expiry keyed by id")]
        JDB[("🔐 join_requests<br/>+ fsub_cache")]
        SDB[("🔧 settings<br/>maintenance flag")]
    end
    U <--> API
    API <--> MAIN & USER
    MAIN --> CH
    USER --> CH
    MAIN --> MW --> FEAT
    FEAT <--> CDB & PDB
    MW <--> JDB & SDB
    WEB --> CDB & PDB

Loading

Two Telegram clients share the process: the main bot client handles all commands, and an optional user-session client (STRING_SESSION) uploads files >2GB. The aiohttp status page lives in the same process on $PORT.

Request pipeline (Pyrogram handler groups)

flowchart LR
    M["📩 any update"] --> G1["🚧 maintenance<br/>group -1<br/>drop + notice"]
    G1 -->|bot alive| G2["🔐 fsub gate<br/>group -10<br/>join check"]
    G2 -->|member| G3["👤 user middleware<br/>register · ban check"]
    G3 --> OK["✅ feature handler<br/>rename · admin · plans"]
    G1 -->|under maintenance| STOP1["⛔ stopped"]
    G2 -->|not joined| STOP2["🔒 join prompt"]
    G3 -->|banned| STOP3["🚫 banned notice"]

Loading

Earlier groups run first and StopPropagation halts the chain — maintenance blocks everything (except bypass IDs), force-subscribe blocks non-members, banned users never reach features.

Rename flow

flowchart TB
    S["📤 user sends file"] --> INFO["📋 rename_start<br/>media info + ForceReply"]
    INFO --> NAME["✏️ refunc<br/>new name → type buttons"]
    NAME --> CB["🔘 upload# callback<br/>document · video · audio"]
    CB --> DL["⬇️ download to Renames/"]
    DL --> META{"🏷️ metadata mode?"}
    META -->|on| FF["🎞️ ffmpeg copy-codec<br/>+ titles → Metadata/"]
    META -->|off| UP["⬆️ upload"]
    FF --> UP
    UP --> TH["🖼️ thumbnail<br/>custom or media · 320px"]
    TH --> BIG{"📦 >2GB?"}
    BIG -->|yes| U4["👤 user-session upload<br/>→ BIN + user, cleanup"]
    BIG -->|no| U2["🤖 bot upload<br/>→ BIN copy, cleanup"]

Loading

Downloads land in Renames/, metadata rewrites in Metadata/, every path is cleaned via remove_path. Premium daily quota is reserved before download and refunded on failure.

Web status page

flowchart LR
    H["🔄 GET /"] --> GS["📊 get_status()<br/>cached counts 60s"]
    H --> SP["🚀 network_speed_label()<br/>Ookla · cached 10min"]
    GS & SP --> T["📝 fill 17 placeholders<br/>welcome.html"]
    T --> R["🌐 styled dashboard"]

Loading

Tech visuals

---

📝 Tech Stack

Layer	Technology	Version	Role
Language	Python	3.14.7 (python:3.14-slim in Docker)	Async runtime, pinned in .python-version
Telegram	Kurigram (+ TgCryptoRust)	2.2.26 / 1.3.1	Pyrogram fork — bot + user-session clients, workers=200
Web	aiohttp	3.14.3	Status dashboard (/, 17-placeholder template)
Database	MongoDB (pymongo AsyncMongoClient)	4.18.1	user (profile + quota) · premium (expiry keyed by id, indexed) · join_requests · fsub_cache · settings — one shared client
Media	ffmpeg / ffprobe	system (Docker-baked)	Duration probe, copy-codec metadata rewrite, 320px thumbnails (Pillow 12.3.0)
Loop	uvloop	0.22.1	Fast event loop, stdlib fallback
Metrics	psutil + Ookla speedtest	7.2.2	CPU/RAM/disk + live network label (10-min cache)
Config	python-dotenv	1.2.3	14 env vars (config.py ↔ app.json ↔ render.yaml, CI-checked)
CI/CD	GitHub Actions + CodeQL + Dependabot	—	build · audit · validate gates, weekly CodeQL + pip updates
Deploy	Docker · Heroku · Render · Koyeb/Railway	—	Dockerfile · app.json · render.yaml in repo

Single-process design: bot + optional 4GB user client + web server share one event loop and one Mongo client — no inter-service wiring, SIGINT/SIGTERM graceful shutdown.

---

✨ Features

• ⚡ Fast File Renaming — Rename files quickly with an efficient Telegram-based workflow.
• 📦 4GB File Support — Process large files with upgraded 4GB support.
• 💎 Premium Plans — Offer upgraded limits and premium capabilities for users.
• 🖼️ Thumbnail Customization — Set permanent custom thumbnails for your files.
• 📝 File Customization — Personalize filenames, captions, prefixes, suffixes, and metadata.
• 🔄 File Conversion — Convert supported files between video and document formats.
• ♾️ Unlimited Renaming — Rename multiple files without a fixed renaming limit.
• 📢 Broadcast System — Send announcements and updates to all registered users.
• 🔐 Force Subscribe — Require users to join configured channels before using the bot.
• 🛡️ User Management — Ban, unban, and manage users directly from the bot.
• 🔧 Maintenance Mode — Temporarily pause bot services whenever maintenance is required.
• 🚀 Multi-Platform Deployment — Deploy easily on Koyeb, Heroku, Railway, and Render.

---

🎥 Quick Start

New to this project?

Watch this short video to understand what the bot is, why it's useful, how it works, explore its key features, and learn the required configuration before deployment.

📺 Watch on YouTube: Project Overview

---

📝 Configuration

Variable	Description
API_ID	Telegram API ID
API_HASH	Telegram API Hash
BOT_TOKEN	Telegram Bot Token
DB_URL	MongoDB URI
DB_NAME	MongoDB database name (default: Rename_Bot)
ADMIN	Telegram User ID
PIC	Start image URL
BIN_CHANNEL	Bin Channel
IS_FSUB	Enable / Disable Force Subscribe
FSUB_EXPIRE	Force Subscribe Expire Time
AUTH_CHANNELS	Force Subscribe Channels
AUTH_REQ_CHANNELS	Request FSUB Channels (membership verified live)
LOG_CHANNEL	Log Channel
STRING_SESSION	Session string required for 4GB file processing
PORT	Web server port (default: 8080)

📝 Notes

💎 4GB Support — STRING_SESSION is optional. Add a Kurigram v2 String Session (Pyrogram-compatible) to enable 4GB file processing.

⚠️ Without STRING_SESSION, the bot will continue to work with its standard file-size limit.

📚 Setup Guides

• 🔑 Telegram API ID & API Hash — Watch Tutorial
• 🤖 Bot Token — Watch Tutorial
• 🍃 MongoDB Database — Watch Tutorial

---

🤖 Commands

👤 User Commands

start - Check Bot Alive.
setprefix - Set Your Prefix
seeprefix - See Your Prefix
delprefix - Delete Your Prefix
viewthumb - To View Current Thumbnail.
delthumb - To Delete Current Thumbnail.
setcaption - To Set A Custom Caption.
seecaption - To See Your Custom Caption.
delcaption - To Delete Custom Caption.
setsuffix - Set Your Suffix
seesuffix - See Your Suffix
delsuffix - Delete Your Suffix
plans - to check all available plans.
myplan - to check your active plan.
metadata - To set custom metadata.

🔒 Owner Commands

ban - ban a user.
unban - unban a user.
banned - list all banned users.
status - get bot statistics.
broadcast - Send message to users.
logs - get recent bot logs.
addpremium - add a user to premium
removepremium - remove a user from premium
restart - restart the bot.
maintenance - Toggle maintenance mode.
delreq - Clear pending force-subscribe join requests.

---

🚀 Deployment

Need help deploying this project? We've got you covered.

Tip

📺 Complete Deployment Playlist — Follow the step-by-step video tutorials to get started.

▶ Watch on YouTube

Prerequisites

• Python 3.14.7 (see .python-version; Docker uses python:3.14-slim)
• ffmpeg on PATH (metadata + thumbnails; ffprobe too)
• MongoDB database (URI for DB_URL)
• Telegram API_ID / API_HASH / BOT_TOKEN, plus ADMIN user ID

Run locally

pip install -r requirements.txt
export API_ID=… API_HASH=… BOT_TOKEN=… ADMIN=… DB_URL=mongodb://localhost:27017 LOG_CHANNEL=…
python bot.py

Deploy targets (all wired in this repo)

Platform	File	Notes
Docker (any host)	Dockerfile	ffmpeg + Ookla speedtest baked in; CMD ["python", "bot.py"] (bot.py entrypoint)
Heroku	app.json, Procfile, heroku.yml	One-click via app.json; all 14 env vars declared
Render	render.yaml (runtime: docker, health check /)	Docker build of Dockerfile (ffmpeg + Ookla inside), autoDeploy: false; all 14 env vars declared
Koyeb / Railway	Dockerfile	Deploy from repo, use the Docker builder, set env vars below

Required environment variables

All 14 are declared in app.json and render.yaml (CI's validate job fails the PR if they drift from config.py):

API_ID · API_HASH · BOT_TOKEN · DB_URL · DB_NAME · ADMIN · PIC · BIN_CHANNEL · LOG_CHANNEL · STRING_SESSION · IS_FSUB · AUTH_CHANNELS · AUTH_REQ_CHANNELS · FSUB_EXPIRE · (PORT is injected by the host, default 8080)

💎 4GB Support — STRING_SESSION is optional. Add a Kurigram v2 String Session (Pyrogram-compatible) to enable 4GB file processing. Without it the bot keeps its standard 2GB limit.

CI — what runs before deploy

Every push/PR runs .github/workflows/ci.yml (badge ↑ top):

Job	What it catches
build	Syntax errors (compileall), bug-class lint (ruff F,E9), plugin wiring (38 handlers + web routes smoke test)
audit	Known CVEs in requirements.txt (pip-audit, advisory)
validate	config.py ↔ app.json ↔ render.yaml env drift · unparseable manifests · Docker base ≠ .python-version · stale welcome.html placeholders · hardcoded secrets / committed session files
CodeQL	Python security analysis (weekly + per-push, config)

---

🤝 Contributing

Contributions are always appreciated! ❤️

🐞 Report Bugs	💡 Suggest Features	🚀 Submit PRs
Found an issue?	Have an idea?	Ready to contribute?
Open Issue	Open Discussion	Fork & Submit

Important

Before opening an issue, please ensure you're using the latest version and have followed the deployment guide.

---

📄 License

Warning

This project is intended strictly for educational purposes only. The author is not responsible for any misuse or abuse. Please comply with all applicable laws and the terms of any third-party services. If you modify or redistribute this project, please provide proper credit to the original repository.

See the LICENSE file for complete details.

---

🫂 Updates & Support

---

🙌 Credits

This repository is based on the original work of:

• Original Developer: DigitalBotz
• Major Contributor: Bisu Ghalan

Note

This repository is maintained by TechifyBots, with improvements to the project presentation and user experience.

👤 Connect With Me

Rahul Dhankhar
_{Open Source Maintainer • TechifyBots}