A powerful desktop application with an intuitive GUI for browsing, searching, and downloading files from Telegram bots. Perfect for managing large collections of media files, TV series, movies, and documents shared through Telegram bots.
- Easy Bot Integration - Connect to any Telegram bot with a simple username
- Advanced Search & Scanning - Search for files across bot messages and all your dialogs
- Intelligent File Detection - Automatically finds files sent by or via specific bots
- Intuitive GUI - User-friendly interface built with Tkinter featuring sidebar navigation
- Real-time Progress Tracking - Embedded progress bars for scanning and downloading
- Cancelable Operations - Stop scans mid-process without losing results
- Recent History - Quick access to recently used bots, searches, and downloads
- Bulk Operations - Handle multiple files and large result sets efficiently
- Direct Downloads - Download selected files directly to your computer with progress tracking
- Export Lists - Export file listings to text files for reference
- Session Management - Saves your login session for quick reconnection
- Auto-connect Option - Optional automatic connection on startup
- Multi-format Support - Handles videos, documents, audio, photos, and more
- Configuration Persistence - All settings and history saved automatically
- Real-time Logging - Track all operations with detailed activity logs
Main application interface with connection panel and search controls and search results
Note: Screenshots are located in the
screenshots/folder. If you haven't added them yet, please create this folder and add your screenshots.
The easiest way to use Telegram Bot File Manager is to download the pre-built executable from the Releases page.
Windows Users:
- Go to Releases
- Download the latest
TG-Bot-Scraper.exe - Run the executable (no installation required)
- Follow the first-time setup instructions below
- Python 3.7 or higher
- Telegram account
- Telegram API credentials (API ID and API Hash)
- Clone the repository
git clone https://github.com/GihanIT/Telegram-Bot-File-Manager.git
cd Telegram-Bot-File-Manager- Install required packages
pip install -r requirements.txtOr install manually:
pip install telethon- Get Telegram API Credentials
- Visit https://my.telegram.org
- Log in with your phone number
- Go to "API Development Tools"
- Create a new application:
- App title:
Telegram Bot File Manager(or any name) - Short name:
tgfilemanager(5-32 alphanumeric characters) - Platform: Select
Desktop - Description: Brief description of your use case
- App title:
- Copy your API ID (number) and API Hash (long string)
python telegram_scraper.py- Launch the application
- Enter your credentials:
- API ID (from Telegram)
- API Hash (from Telegram)
- Phone number (with country code, e.g.,
+94771234567)
- Optional: Check "Auto connect on startup" for automatic connection
- Click "Connect"
- Enter verification code when prompted (check your Telegram app)
- If you have 2FA enabled, enter your password when asked
Your credentials and session are saved automatically for future use.
- Enter Bot Username (e.g.,
@YourBotNameorYourBotName)- Click on recently used bots in the sidebar for quick access
- Enter Search Query (e.g.,
Breaking Bad Season 1)- Or select from recent searches in the sidebar
- Set Max Messages per Chat (default: 200)
- Enable/Disable "Scan all chats":
- Enabled: Scans all your dialogs for files from the bot (comprehensive but slower)
- Disabled: Only searches the bot's private messages (faster)
- Click "Search Files"
- Monitor progress in the embedded progress bar
- Stop scanning anytime by clicking "Stop Scan"
- Results populate in the table as they're found
The results table displays:
- Idx: Result index number
- Chat: Where the file was found (bot PM or other chat)
- MsgID: Telegram message ID
- FileName: Name of the file
- Size: File size in human-readable format
- Type: File type (video, document, audio, photo, etc.)
- Date: When the file was posted
- Select a file from the results table
- Double-click to view details OR
- Click "Download Selected" to start download
- Monitor download progress in the embedded progress bar
- Files are saved to the folder specified in "Save folder" (default:
downloads/) - Recent downloads appear in the sidebar for quick reference
- Clear Results: Remove all search results from the table
- Export List: Save current results to
file_list.txtwith detailed information - Recent Sidebar: Quick access to:
- Recently used bots (click to autofill)
- Recent searches (click to autofill)
- Recent downloads (double-click to view path)
- Activity Log: Monitor all operations in real-time at the bottom of the window
- Disconnect: Safely disconnect from Telegram when done
Settings are automatically saved to config.json including:
- API credentials (for convenience)
- Phone number
- Auto-connect preference
- Recently used bots (up to 12)
- Recent searches (up to 12)
- Recent downloads (up to 12)
Session files are automatically created as session_<phone_number>.session. These files store your authentication and allow quick reconnection without re-entering codes.
To reset your session:
# Delete session files
rm session_*.session
# Or on Windows
del session_*.sessionBy default, files are downloaded to the downloads/ folder in the application directory. You can change this in the "Save folder" field before downloading.
The folder is created automatically if it doesn't exist.
telethon>=1.24.0
- Media Management: Browse and download movies, TV series, and documentaries
- File Organization: Search through large bot archives efficiently
- Batch Downloads: Queue multiple files for download
- Content Discovery: Explore file collections without manual scrolling
- Archive Creation: Export file lists for cataloging
- Cross-Chat Search: Find files from a specific bot across all your chats
Bot PM Search:
- Sends your query to the bot
- Searches the bot's private messages
- Fast and targeted
All Chats Scan (when enabled):
- Scans up to 500 of your recent dialogs
- Finds files sent by, via, or forwarded from the specified bot
- Comprehensive but takes longer
- Shows real-time progress with percentage
The application detects files that are:
- Directly from the bot
- Sent via the bot (inline)
- Forwarded from the bot
- Documents, videos, audio, photos
- Text references containing file extensions
- Rate Limits: Telegram has rate limits. The app includes delays to prevent issues
- Bot Permissions: Make sure you have access to the bot before searching
- Legal Use: Only download content you have rights to access
- Session Security: Keep your session files secure and private
- API Credentials: Never share your API ID, API Hash, or session files
- Scan Time: Full dialog scans can take several minutes depending on your chat count
- Internet Connection: Stable connection required for best performance
- Verify your API ID and API Hash are correct
- Check your internet connection
- Delete old session files and try again
- Ensure you're entering the verification code correctly
- Close the application completely
- Delete session files (
session_*.session) - Restart the application
- Make sure the bot username is correct (with or without @)
- Verify you have started the bot at least once in Telegram
- Check if the bot is currently active
- Try sending a message to the bot manually first
- Try different search terms
- Increase "Max messages per chat" limit
- Enable "Scan all chats" for comprehensive search
- Wait a few seconds after the search completes
- Some bots may require specific command formats
- Disable "Scan all chats" for faster bot PM-only search
- Reduce "Max messages per chat" value
- Use more specific search queries
- Click "Stop Scan" if you have enough results
- Check your internet connection
- Ensure you have write permissions to the download folder
- Verify sufficient disk space
- Try downloading again (Telegram may have temporary issues)
- Your credentials are stored locally in
config.json - Session files are encrypted by Telethon
- No data is sent to third parties
- API credentials are never logged
- All operations are performed directly with Telegram's servers
- You can delete
config.jsonand session files anytime to clear stored data
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! We'd love your help to make this project even better.
- Fork the project
- Create your feature branch
git checkout -b feature/AmazingFeature
- Commit your changes
git commit -m 'Add some AmazingFeature' - Push to the branch
git push origin feature/AmazingFeature
- Open a Pull Request
- Add new search filters and sorting options
- Implement batch download functionality
- Add support for more file types
- Improve UI/UX design
- Add multi-language support
- Create better error handling
- Write unit tests
- Improve documentation
- Add new features you think would be useful
Found a bug or have a suggestion? Please open an issue on GitHub with:
- Clear description of the problem or suggestion
- Steps to reproduce (for bugs)
- Expected vs actual behavior
- Screenshots if applicable
- Your environment (OS, Python version, etc.)
- Built with Telethon - Powerful Telegram client library
- GUI powered by Tkinter - Python's standard GUI framework
- Inspired by the need for better Telegram bot file management
- Thanks to all contributors who help improve this project
Project Link: https://github.com/GihanIT/Telegram-Bot-File-Manager
Issues & Support: GitHub Issues
Give a ⭐️ if this project helped you! Your support motivates continued development.
- Language: Python
- GUI Framework: Tkinter
- Telegram Library: Telethon
- License: MIT
- Status: Active Development
Disclaimer: This tool is for personal use only. Respect copyright laws and Telegram's Terms of Service. The developers are not responsible for misuse of this software. Use responsibly and only access content you have permission to download.