A powerful Telegram auto-filter bot built with Pyrogram
Index your channels · Serve files · Manage groups with ease
| Feature | Status |
|---|---|
| Auto Filter | ✅ |
| Manual Filter | ✅ |
| IMDb Info & Search (imdbio → OMDb backup) | ✅ |
| 🎬 Telegram Mini App (poster grid, search, send to PM) | ✅ |
| 🌐 Public Website (posters, search, one-tap Telegram delivery) | ✅ |
| Multi-select & Send All with ✅ ticks | ✅ |
| Auto-Delete of Sent Files (+ "Delete Now" button) | ✅ |
| Full, Untrimmed File Names | ✅ |
| Inline Search | ✅ |
| Spelling Check & Suggestions | ✅ |
| Language & Quality Filters | ✅ |
| File Store with Auto-Delete | ✅ |
| Fast Broadcast to All Users | ✅ |
| Index Channels | ✅ |
| Admin Commands | ✅ |
| Group Connection via PM | ✅ |
| Ban / Unban Users & Chats | ✅ |
| User & Chat Statistics | ✅ |
| Protect Content | ✅ |
| Force Subscribe Channel Check | ✅ |
| Auto Approve Join Requests | ✅ |
| Per-Group Settings | ✅ |
| 24-Hour Auto Restart | ✅ |
Copy sample_info.py → info.py and fill in your values, or set them as environment variables for cloud deployments.
| Variable | Description |
|---|---|
BOT_TOKEN |
Get from @BotFather |
API_ID |
Get from my.telegram.org |
API_HASH |
Get from my.telegram.org |
CHANNELS |
Username or ID of channels to index (space-separated) |
ADMINS |
Username or ID of bot admins (space-separated) |
DATABASE_URI |
MongoDB connection URI — get one free |
DATABASE_NAME |
Name of your MongoDB database |
LOG_CHANNEL |
Channel ID for bot activity logs (bot must be admin) |
| Variable | Default | Description |
|---|---|---|
PICS |
Telegra.ph URLs | Space-separated image links shown on /start |
FILE_STORE_CHANNEL |
— | Channel IDs for file store links (space-separated) |
AUTH_CHANNEL |
— | Force-subscribe channel ID |
AUTH_USERS |
— | Extra user IDs with admin access |
AUTH_GROUP |
— | Allowed group IDs (space-separated) |
CACHE_TIME |
300 |
Inline query cache time (seconds) |
CUSTOM_FILE_CAPTION |
Script default | Caption template for sent files |
BATCH_FILE_CAPTION |
Built-in | Caption used in batch file links |
IMDB_TEMPLATE |
Built-in | Template for IMDB result messages |
IMDB |
False |
Show IMDB info on search results |
LONG_IMDB_DESCRIPTION |
False |
Use full plot instead of short summary |
SINGLE_BUTTON |
True |
Show filename + size in one button |
P_TTI_SHOW_OFF |
True |
Redirect users to bot PM instead of sending file in group |
SPELL_CHECK_REPLY |
True |
Suggest similar titles when file not found |
MAX_LIST_ELM |
None |
Limit cast/crew list length in IMDB template |
PROTECT_CONTENT |
False |
Enable forward-protection on sent files |
PUBLIC_FILE_STORE |
False |
Allow any user to create file store links |
MELCOW_NEW_USERS |
True |
Send welcome message to new users |
MINIAPP_URL |
— | Public HTTPS URL of your bot's web server (e.g. https://yourapp.koyeb.app). Enables the 🎬 Open Mini App button and /app |
OMDB_API_KEY |
— | Free key from omdbapi.com. Backup poster/info source when imdbio is blocked, and gives HD posters |
TMDB_API_KEY |
— | Optional. Mini App only — last-resort poster fallback |
AUTO_DELETE_TIME |
600 |
Seconds before sent files are deleted from the user's PM. 0 disables |
COLLECTION_NAME |
Telegram_files |
MongoDB collection name for indexed files |
INDEX_REQ_CHANNEL |
LOG_CHANNEL |
Channel where index requests are logged |
Full list with defaults:
info.py· Example config:sample_info.py
Your bot's web address (e.g. https://yourapp.koyeb.app) now opens a movie website: poster grid, search, quality / language filters, movie pages with details and every file, light & dark theme, mobile friendly.
- Get a file: tap Get on Telegram → the bot opens and sends the file to your chat (ban list, force-subscribe and auto-delete still apply). Nothing is downloaded from the site itself.
- Safe by design: the site never shows Telegram file IDs, each file gets a short token (stored in Mongo, auto-expires after 14 days); API is rate-limited per IP.
- Shareable: every movie page has its own link (
/#/m/...), with a Share button. - No extra setup — it uses the same database and poster keys (
OMDB_API_KEY, optionalTMDB_API_KEY)./healthreturnsokfor uptime checks.
A movie-poster browser that opens inside Telegram.
- Poster grid — search, then tap a poster to open the movie page
- Movie page — full-size poster, rating, genres, plot, quality chips and every file of that movie
- Select files → send to PM — pick one or many, the bot sends them to your chat and they auto-delete after
AUTO_DELETE_TIME - No duplicates — different filenames of the same movie are merged into one card; subtitles / audio files never get their own card; the same file indexed twice is shown once
- Poster chain — imdbio → OMDb → TMDB (optional), cached in memory
Set it up
- Deploy the bot and set
MINIAPP_URL=https://<your-app>.koyeb.app(the/apppart is added for you). - In @BotFather:
/mybots→ your bot → Bot Settings → Menu Button → Configure menu button → send the same URL ending with/app, and a title likeKuttuBot. - Open the bot → tap 🎬 Open Mini App on
/start, or send/app.
All mini app calls are verified with Telegram initData (HMAC-SHA256 with your bot token), banned users and force-subscribe rules are respected.
Click to expand
Click to expand
git clone https://github.com/GouthamSER/KuttuBot
cd KuttuBot
# Set your variables in info.py or as environment vars
docker-compose up -dDockerfile and docker-compose.yml are included in the repo.
Click to expand
# Requires Python 3.10+
git clone https://github.com/GouthamSER/KuttuBot
cd KuttuBot
pip3 install -U -r requirements.txt
cp sample_info.py info.py
# Edit info.py with your values
python3 bot.py| Command | Description |
|---|---|
/start |
Start the bot |
/help |
Get help info |
/about |
About the bot |
/id |
Get your Telegram ID |
/info |
Get info about a user |
/imdb |
Search a movie on IMDb |
/app |
Open the Mini App (needs MINIAPP_URL) |
| Command | Description |
|---|---|
/filter |
Add a manual filter |
/filters |
View all filters in this group |
/del |
Delete a specific filter |
/delall |
Delete all filters |
/connect |
Connect a group to your PM |
/disconnect |
Disconnect from current group |
/connections |
List your active connections |
/settings |
Configure per-group settings |
| Command | Description |
|---|---|
/broadcast |
Broadcast a message to all users |
/index |
Index files from a channel |
/deleteall |
Delete all indexed files |
/delete |
Delete a specific indexed file |
/stats |
View database and file stats |
/users |
List all users |
/chats |
List all chats |
/logs |
Get recent error logs |
/batch |
Create a shareable link for multiple posts |
/link |
Create a shareable link for a single post |
/ban |
Ban a user from the bot |
/unban |
Unban a user |
/leave |
Make the bot leave a chat |
/disable |
Disable the bot in a chat |
/enable |
Re-enable the bot in a chat |
/channel |
List all connected channels |
KuttuBot/
├── bot.py # Entry point & Bot class
├── info.py # All configuration variables
├── sample_info.py # Config template (copy → info.py)
├── utils.py # Shared async utilities
├── Script.py # All message texts & templates
├── requirements.txt # Python dependencies
├── Dockerfile # Docker container config
├── docker-compose.yml # Docker Compose config
├── plugins/
│ ├── pm_filter.py # Auto filter, Language & Quality callbacks
│ ├── filters.py # Manual filter management
│ ├── broadcast.py # Fast broadcast system
│ ├── index.py # Channel indexing
│ ├── inline.py # Inline search
│ ├── connection.py # PM ↔ group connection
│ ├── commands.py # Start, help, file store & user commands
│ ├── channel.py # Channel media handler
│ ├── miniapp.py # Mini App API (search, movie, send) + initData auth
│ ├── website.py # Public website API + token links
│ ├── posters.py # Filename parser + poster/info lookup (imdbio → OMDb → TMDB)
│ ├── webcode.py # aiohttp web server routes
│ ├── misc.py # ID, info, IMDb commands
│ ├── auto_approve.py # Auto join request approval
│ ├── banned.py # Banned user/chat middleware
│ ├── mov_ser_latest.py # Latest movies & series listing
│ └── etc.py # Extra/miscellaneous commands
├── miniapp/
│ └── index.html # Mini App front-end (single file)
├── site/
│ └── index.html # Public website front-end (single file)
└── database/
├── ia_filterdb.py # Indexed file database (with search cache)
├── filters_mdb.py # Manual filter database
├── users_chats_db.py # Users & chats database
└── connections_mdb.py # PM–group connection database
- 🌐 Website — public movie site at your bot's URL, files delivered through the bot with short expiring tokens
- 🎬 Mini App — poster grid → movie page → pick files → sent to your PM, header "KuttuBot · by Goutham Josh"
- 🧩 Duplicate fix — one card per movie (merged by IMDb id), no subtitle cards, exact re-indexed files shown once
- 🖼️ HD posters — imdbio first, OMDb backup, optional TMDB; full-resolution image on tap
- ☑️ Select & Send All — "Select Files" button on top, ✅ ticks, Send All to PM, Back button
- ⏳ Auto-delete — sent files are removed after
AUTO_DELETE_TIMEwith a "🗑 Delete Now" button - 📝 Full file names — no truncation in buttons or captions
- ⚡ Auto-filter speed —
get_settingsandget_search_resultsnow run in parallel viaasyncio.gather; typing action fires as a background task so the DB query starts instantly - 🗑️ Cleaned filter buttons — removed Years, Seasons, Episodes and Send All; only Language & Quality filters remain
- 🧹 Dead code removed — ~300 lines of unused handlers and data lists eliminated from
pm_filter.py - 🔍 Search cache — repeated queries within 60 s return instantly from memory (no DB round-trip)
- ⚡ Broadcast speed — removed per-user 2-second delay; broadcasts are now ~40× faster
- 🔧 FloodWait fix — updated
e.x→e.valuefor Pyrogram v2+ compatibility - 🌐 Async HTTP — replaced blocking
requestslibrary withaiohttpfor non-blocking searches - 🐛 Search result bug — fixed crash when regex fails in
get_search_results()(wrong return type) - 📦 Inline search fix — removed deprecated
pyrogram.emojiimport that caused startup crash
- Pyrogram by Dan — the MTProto library powering this bot
- EvaMaria by Mahesh & Ritesh — original bot base
- TroJanZ — AutoFilterBot base
- Goutham Josh — repo maintainer, features & bug fixes
- Everyone who starred, forked, and contributed 💙
Licensed under GNU AGPL v3.0.
Selling this code for money is strictly prohibited.
Forking for personal use is welcome — please credit the original authors and do not rebrand as your own work. Respect the community that built this. 🙏