📱 Telegram Tools by Ubden®

Professional Telegram Automation Solution

A powerful Python-based Telegram automation tool with an intuitive graphical interface for member scraping, adding, and bulk messaging operations.

Features • Installation • Usage • Documentation • Releases

---

Developer: Can Kurt | @ck-cankurt
Organization: Ubden® | ubden.com

---

⚠️ Disclaimer / Sorumluluk Reddi

IMPORTANT LEGAL NOTICE / ÖNEMLİ YASAL UYARI

English: This tool is provided for educational and research purposes only. The developers and contributors of this project are not responsible for any misuse, damage, or legal consequences resulting from the use of this software. Users are solely responsible for ensuring their usage complies with:

• Telegram's Terms of Service
• Local and international laws and regulations
• Privacy and data protection regulations (GDPR, KVKK, etc.)
• Anti-spam and communication laws

Automated actions on Telegram may result in account restrictions, bans, or legal action. Use at your own risk. By using this software, you acknowledge and accept full responsibility for your actions.

---

Türkçe: Bu araç yalnızca eğitim ve araştırma amaçlıdır. Bu projenin geliştiricileri ve katkıda bulunanlar, bu yazılımın kullanımından kaynaklanan herhangi bir kötüye kullanım, hasar veya yasal sonuçtan sorumlu değildir. Kullanıcılar, kullanımlarının aşağıdakilere uygun olduğundan emin olmaktan yalnızca kendileri sorumludur:

• Telegram Kullanım Şartları
• Yerel ve uluslararası yasa ve düzenlemeler
• Gizlilik ve veri koruma düzenlemeleri (GDPR, KVKK, vb.)
• Spam önleme ve iletişim yasaları

Telegram'da otomatik işlemler hesap kısıtlamalarına, yasaklamalara veya yasal işlemlere yol açabilir. Riski size aittir. Bu yazılımı kullanarak, eylemlerinizin tüm sorumluluğunu kabul ettiğinizi onaylarsınız.

---

🚀 Features

Feature	Description
👥 Multi-Account Support	Configure and use multiple Telegram accounts simultaneously
🔍 Member Scraping	Extract member information from Telegram groups with precision
➕ Member Adding	Add scraped members to target channels/groups efficiently
💬 Bulk Messaging	Send private messages to multiple group members at once
🌐 Proxy Support	Route API requests through HTTP proxies with authentication
⏱️ Flood Control	Configurable delays to avoid Telegram rate limits
🔐 Secure Storage	Encrypted configuration and session management
🇹🇷 Turkish Interface	Fully localized Turkish GUI with detailed instructions
🔑 GUI Authentication	In-app authentication dialogs (no terminal input needed)

---

📋 Requirements

• Python 3.8 or higher
• Telegram API credentials (API ID and API Hash)
• Internet connection for Telegram API access
• Operating System: Windows, Linux, or macOS

---

🔧 Installation

Method 1: Quick Start (Recommended)

# Clone the repository
git clone https://github.com/ubden/telegram-tools.git
cd telegram-tools

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python main.py

Method 2: Pre-Built Executable (Windows Only)

1. Visit the Releases page
2. Download the latest TelegramTools-vX.X.X.exe
3. Run the executable - no installation required!

---

🔑 How to Get Telegram API Credentials

graph LR
    A[Visit my.telegram.org] --> B[Login with phone]
    B --> C[API development tools]
    C --> D[Fill application details]
    D --> E[Create application]
    E --> F[Copy API ID & Hash]

Loading

Step-by-Step Guide:

1. 🌐 Go to https://my.telegram.org
2. 📱 Log in with your phone number
3. 🛠️ Click on "API development tools"
4. 📝 Fill in the application details:
   • App title: Any name (e.g., "My Telegram Tools")
   • Short name: Any short name (e.g., "mytools")
   • Platform: Desktop
5. ✅ Click "Create application"
6. 📋 Copy your API ID and API Hash

---

🎯 Usage Guide

1️⃣ Configuration Tab (Yapılandırma)

Click to expand configuration steps

• Enter your API IDs and API Hashes (comma-separated for multiple accounts)
• Configure proxy settings (optional)
• Set flood control time (delay between operations in seconds)
• Enter source group and target channel names
• Click "Bilgileri Kaydet" to save

2️⃣ Member Scraping & Adding (Üye Toplama-Ekleme)

Click to expand scraping & adding steps

• Ensure configuration is saved
• Click "İşlemi Başlat" to begin
• First time authentication:
  • Enter phone number (e.g., +905551234567)
  • Enter verification code from Telegram
  • Enter 2FA password if enabled
• Monitor progress in the log area
• View success/failure statistics

3️⃣ Bulk Messaging (Toplu Mesaj)

Click to expand bulk messaging steps

Adding Groups:

• Type group name or link in the input field
• Click "➕ Ekle" or press Enter
• Format: @groupname or https://t.me/groupname

Sending Messages:

• Select groups from the list (Ctrl+Click for multiple)
• Write your message in the text area
• Click "Mesaj Gönder" to start sending
• Monitor progress and statistics

Group Management:

• ➕ Ekle: Add new group to list
• 🗑️ Seçileni Sil: Remove selected groups
• 🗑️ Tümünü Temizle: Clear all groups

---

📁 Project Structure

telegram-tools/
├── 📂 src/                    # Source code
│   ├── 📄 config.py          # Configuration management
│   ├── 📄 session_manager.py # Telegram session handling
│   ├── 📄 scraper.py         # Member scraping module
│   ├── 📄 adder.py           # Member adding module
│   ├── 📄 bulk_messenger.py  # Bulk messaging module
│   ├── 📄 flood_controller.py# Rate limiting
│   ├── 📄 gui.py             # Graphical user interface
│   ├── 📄 logger.py          # Logging configuration
│   └── 📄 models.py          # Data models
├── 📂 tests/                  # Test suite
├── 📂 config/                 # Configuration directory
├── 📄 main.py                # Application entry point
├── 📄 requirements.txt       # Python dependencies
├── 📄 README.md             # This file
└── 📄 .github/workflows/     # CI/CD workflows

---

🔒 Security & Privacy

Component	Security Measure
🔐 API Credentials	Fernet encryption
💾 Configuration	~/.telegram-tools/config.json (encrypted)
📱 Session Files	~/.telegram-tools/sessions/ (encrypted)
📝 Logs	~/.telegram-tools/app.log

Note: All sensitive data is encrypted using industry-standard Fernet encryption to ensure maximum security.

---

⚠️ Important Notes

⚡ Respect Telegram's Terms of Service: Excessive automation may result in account restrictions
⏱️ Use Flood Control: Set appropriate delays (recommended: 30-60 seconds)
🧪 Test with Small Groups: Start with small groups to test functionality
💾 Backup Sessions: Keep backup of session files to avoid re-authentication

---

🧪 Testing

Run tests using pytest:

# Run all tests
python -m pytest tests/ -v

# Run specific test categories
python -m pytest tests/test_config.py -v
python -m pytest tests/test_session_manager.py -v

---

📦 Releases & Downloads

📥 Downloading Pre-Built Executables

For Windows users who don't want to install Python:

1. Go to the Releases page
2. Download the latest TelegramTools-vX.X.X.exe file
3. Run the executable - no installation required!

System Requirements:

• ✅ Windows 7 or later
• ✅ No Python installation needed
• ✅ No additional dependencies required

🚀 Creating a New Release

Releases are created automatically using GitHub Actions when you push a version tag.

Click to expand release process

Step-by-Step Release Process:

1. Ensure your code is ready:

   git status
   git add .
   git commit -m "Prepare for release v1.0.0"

2. Create and push a version tag:

   # Create an annotated tag
   git tag -a v1.0.0 -m "Release version 1.0.0 - Initial stable release"
   
   # Push the tag to GitHub
   git push origin v1.0.0

3. Monitor the workflow:

   • Go to the Actions tab
   • Watch the "Build and Release" workflow execute

4. Verify the release:

   • Check the Releases page
   • Download and test the executable

---

🐛 Troubleshooting

❌ "Can't find a usable init.tcl" Error

• This is automatically fixed by the application
• If persists, ensure Python is properly installed with tkinter support

🔑 Authentication Issues

• Ensure phone number includes country code (e.g., +905551234567)
• Check that verification code is entered correctly
• Verify 2FA password if enabled

🔐 "The key is not registered" Error

• Session needs authentication
• Delete session files in ~/.telegram-tools/sessions/ and re-authenticate

⏱️ Flood Errors

• Increase flood control time in configuration
• Wait before retrying operations
• Use fewer accounts or slower operation speed

---

📚 Dependencies

Package	Version	Purpose
telethon	>=1.34.0	Telegram API client library
cryptography	>=41.0.0	Encryption for sensitive data
hypothesis	>=6.92.0	Property-based testing
tkinter	Built-in	GUI framework

---

🤝 Contributing

Contributions are welcome! Please feel free to:

• 🐛 Report bugs
• 💡 Suggest new features
• 🔧 Submit pull requests
• 📖 Improve documentation

---

💖 Support & Donate

If you find this project useful, consider supporting the development:

☕ Donate via Ubden Donate & Sponsor

Ubden Link Shortener and Social Tools
Support the project and get access to premium features!

Your support helps maintain and improve this project. Thank you! ❤️

---

👨‍💻 Developer

Can Kurt

---

🌟 Follow Us

Stay updated with the latest developments:

Organization: github.com/ubden
Developer: github.com/ck-cankurt

---

📄 License

License to be determined. Please contact the developer for usage permissions.

---

Telegram Tools by Ubden®

Professional Telegram Automation Solution

Made with ❤️ by Can Kurt

---

⭐ Star this repository if you find it useful! ⭐