🤖 3XUI Panel Client Management Bot

🚀 A powerful, modern Telegram bot for seamless 3XUI panel client management

✨ Features • 🚀 Quick Start • 📖 Commands • 🛠️ Installation • 🤝 Contributing

✨ Features

🎯 Core Client Management

🆕 Create Clients - Instant client creation with smart configuration
👀 View Details - Comprehensive client information display
🗑️ Delete Clients - Safe removal with confirmation prompts
📋 List All - Paginated client listings for easy browsing
🔍 Smart Search - Find clients by email, name, or keywords
⚡ Bulk Operations - Manage multiple clients simultaneously

📊 Advanced Features

🔒 Multi-Protocol - Support for VLESS, VMess, and Trojan protocols
🌐 Inbound Management - Handle multiple server configurations
⚙️ Flexible Config - Customizable client settings and limits
📱 QR Codes - Generate connection QR codes instantly
🔄 Auto-Management - Automated client operations

🛡️ Security & Control

🔐 Admin Access - Secure admin-only bot control
📝 Activity Logs - Detailed operation tracking
🚫 Rate Limiting - Protection against abuse
🔒 Secure API - Encrypted communication with 3XUI panel

🚀 Quick Start

🐳 Docker Deployment (Recommended)

# 📥 Clone the repository
git clone https://github.com/noobconner21/3XUI-Panel-Client-Management-Telegram-Bot.git
cd 3XUI-Panel-Client-Management-Telegram-Bot

# 🔧 Setup environment
cd docker
cp .env.example .env
nano .env  # Configure your settings

# 🚀 Launch with Docker
docker-compose up -d

🐍 Manual Installation

# 📥 Clone and setup
git clone https://github.com/noobconner21/3XUI-Panel-Client-Management-Telegram-Bot.git
cd 3XUI-Panel-Client-Management-Telegram-Bot

# 📦 Install dependencies
pip install -r requirements.txt

# 🔧 Configure environment
cp docker/.env.example .env
nano .env

# 🚀 Start the bot
python src/main.py

🔧 Configuration

📋 Environment Setup

Create your .env file with these essential variables:

# 🤖 Telegram Bot Configuration
BOT_TOKEN=your_bot_token_from_botfather
ADMIN_USER_ID=your_telegram_user_id

# 🌐 3xUI Panel Settings  
XUI_HOST=https://your-panel-domain.com
XUI_USERNAME=admin
XUI_PASSWORD=your_secure_password

# ⚙️ Optional Settings
LOG_LEVEL=INFO
SESSION_TIMEOUT=3600

🔑 Getting Your Credentials

What you need	How to get it	Bot to message
🤖 Bot Token	Create a new bot	@BotFather
👤 User ID	Get your Telegram ID	@userinfobot
🌐 Panel URL	Your 3XUI web interface	`https://your-server-ip:port`

---

📖 Commands

🎮 Bot Commands

Command	Description	Example Usage
`🏁 /start`	Initialize and welcome	`/start`
`❓ /help`	Show help menu	`/help`
`➕ /create`	Create new client	`/create user@domain.com`
`📋 /list`	List all clients	`/list`
`ℹ️ /info`	Get client details	`/info user@domain.com`
`🗑️ /delete`	Remove client	`/delete user@domain.com`
`🔍 /search`	Search clients	`/search keyword`
`📊 /stats`	System statistics	`/stats`

🛠️ Advanced Usage

🆕 Create clients with custom settings:

/create user@example.com --protocol vless --limit 100GB --expire 30d

📊 Get detailed client info:

/info user@example.com

🔍 Smart search across clients:

/search example  # Finds all clients matching "example"

🛠️ Installation

🐳 Docker Installation (Recommended)

📋 Prerequisites

Docker and Docker Compose installed
3XUI panel running and accessible
Telegram bot token from @BotFather

🚀 Step-by-Step Setup

📥 Clone Repository

git clone https://github.com/noobconner21/3XUI-Panel-Client-Management-Telegram-Bot.git
cd 3XUI-Panel-Client-Management-Telegram-Bot

🔧 Configure Environment

cd docker
cp .env.example .env

Edit .env with your settings:

# 🤖 Telegram Configuration
BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
ADMIN_USER_ID=123456789

# 🌐 3XUI Panel Configuration  
XUI_HOST=https://your-panel.com:2053
XUI_USERNAME=admin
XUI_PASSWORD=your_secure_password

# ⚙️ Optional Configuration
LOG_LEVEL=INFO
SESSION_TIMEOUT=3600

🚀 Deploy Application

docker-compose up -d

✅ Verify Installation

docker-compose logs -f xui-bot

🐍 Manual Installation

📋 Prerequisites

Python 3.11 or higher
pip package manager
Virtual environment (recommended)

🚀 Step-by-Step Setup

📥 Clone Repository

git clone https://github.com/noobconner21/3XUI-Panel-Client-Management-Telegram-Bot.git
cd 3XUI-Panel-Client-Management-Telegram-Bot

🐍 Setup Python Environment

# Create virtual environment
python -m venv venv

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

📦 Install Dependencies

pip install -r requirements.txt

🔧 Configure Environment

cp docker/.env.example .env
nano .env  # Edit with your settings

🚀 Run the Bot

python src/main.py

🏗️ Project Structure

🗂️ 3XUI-Panel-Client-Management-Telegram-Bot/
├── 📁 src/                     # 🐍 Source code
│   ├── 🚀 main.py              # Main application entry
│   ├── ⚙️ config_manager.py    # Configuration handler
│   ├── 📝 logger_setup.py      # Logging system
│   ├── 🌐 xui_client.py        # 3XUI API client
│   └── 🛠️ utils.py             # Helper utilities
├── 📁 docker/                  # 🐳 Container files
│   ├── 🐳 Dockerfile           # Container definition
│   ├── 🐙 docker-compose.yml   # Orchestration config
│   └── 📄 .env.example         # Environment template
├── 📦 requirements.txt         # Python dependencies
├── 📜 LICENSE                  # MIT License
└── 📖 README.md               # This documentation

🤝 Contributing

We welcome contributions! Here's how you can help:

🔧 Development Setup

# 🍴 Fork and clone
git clone https://github.com/your-username/3XUI-Panel-Client-Management-Telegram-Bot.git
cd 3XUI-Panel-Client-Management-Telegram-Bot

# 🐍 Setup Python environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 📦 Install dependencies
pip install -r requirements.txt

# 🔧 Configure environment
cp docker/.env.example .env
# Edit .env with your settings

# 🚀 Run for development
python src/main.py

📝 Contribution Guidelines

🍴 Fork the repository
🌿 Create your feature branch (git checkout -b feature/amazing-feature)
✨ Commit your changes (git commit -m 'Add amazing feature')
📤 Push to the branch (git push origin feature/amazing-feature)
🔄 Open a Pull Request

🆘 Troubleshooting

🐛 Common Issues

🤖 Bot not responding

Possible causes:

❌ Incorrect bot token
❌ Bot not initialized with /start
❌ Wrong admin user ID
❌ Network connectivity issues

Solutions:

✅ Verify bot token is correct in .env
✅ Send /start command to initialize bot
✅ Check admin user ID is properly configured
✅ Test bot token with @BotFather

🌐 3XUI connection failed

Possible causes:

❌ Incorrect panel URL or credentials
❌ Network connectivity issues
❌ Firewall blocking access
❌ 3XUI panel not running

Solutions:

✅ Verify panel URL and credentials in browser
✅ Check network connectivity to panel
✅ Ensure 3XUI panel is running and accessible
✅ Check firewall settings and port access

🚫 Permission denied

Possible causes:

❌ User not configured as admin
❌ Incorrect admin user ID
❌ Bot doesn't have necessary permissions

Solutions:

✅ Verify admin user ID in configuration
✅ Get correct user ID from @userinfobot
✅ Ensure bot has proper Telegram permissions

🐳 Docker issues

Possible causes:

❌ Docker not installed or running
❌ Port conflicts
❌ Environment variables not set

Solutions:

✅ Install Docker and Docker Compose
✅ Check for port conflicts (docker-compose ps)
✅ Verify .env file configuration
✅ Restart Docker daemon if needed

📋 Viewing Logs

🐳 Docker logs:

# View bot logs
docker-compose logs -f xui-bot

# View all services
docker-compose logs -f

🐍 Manual installation logs:

# Real-time logs
tail -f logs/bot.log

# All logs
cat logs/bot.log

🔧 Debug Mode

Enable debug logging by setting in .env:

LOG_LEVEL=DEBUG

❓ FAQ

❓ Can multiple admins use the bot?

Currently supports single admin configuration. Multi-admin support is planned for future releases.

❓ Does it work with other x-ui panels?

This bot is specifically designed for 3x-ui panels. Compatibility with other x-ui variants is not guaranteed.

❓ Can I customize client configurations?

Yes! The bot supports various client configuration options through command parameters and settings.

❓ Is there a web interface?

Currently, this is a Telegram-only bot. Web interface support may be considered for future versions.

❓ How secure is the bot?

The bot uses secure API communication, admin-only access control, and follows Telegram security best practices.

❓ Can I run multiple instances?

Yes, you can run multiple instances with different configurations for different panels or admin groups.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License - you are free to:
✅ Use commercially
✅ Modify and distribute  
✅ Use privately
✅ Sublicense

💬 Support & Community

📞 Need help? Open an issue • 💡 Have ideas? Start a discussion • 🐛 Found a bug? Report it

📞 Getting Help

📖 Check Documentation - Review this README and troubleshooting section
🔍 Search Issues - Look for existing solutions in GitHub Issues
💬 Community Discussion - Join discussions for feature requests and general questions
🐛 Report Bugs - Create detailed issue reports with logs and steps to reproduce

🤝 Community Guidelines

🎯 Be respectful and constructive
📝 Provide detailed information when reporting issues
🔍 Search for existing issues before creating new ones
✨ Contribute with code, documentation, or testing

🚀 Roadmap

📅 Planned Features

🔄 v1.1: Multi-admin support
📊 v1.2: Advanced traffic analytics
📱 v1.3: Mobile app companion
🌐 v1.4: Web dashboard interface
🤖 v1.5: AI-powered client management
🔗 v1.6: Multi-panel support

🎯 Current Focus

🐛 Bug fixes and stability improvements
📚 Documentation enhancements
🔧 Configuration simplification
🚀 Performance optimizations

🙏 Acknowledgments

🎯 3x-ui Project - For the excellent panel software
🤖 Telegram Bot API - For the robust bot framework
🐳 Docker Community - For containerization support
🐍 Python Community - For the amazing ecosystem
🌟 Contributors - For making this project better

📈 Stats

⭐ Found this helpful? Give it a star!

🚀 Ready to manage your 3XUI clients like a pro?

Made with ❤️ for the 3XUI community

```

Run:

python src/main.py

Bot Commands

User Commands

/start - Initialize bot
/help - Show help message
/status - Panel status
/clients - List clients

Admin Commands

/addclient <email> - Add new client
/delclient <email> - Delete client
/enable <email> - Enable client
/disable <email> - Disable client
/traffic - Traffic statistics

Project Structure

├── src/                 # Source code
│   ├── main.py         # Main bot application
│   ├── config_manager.py
│   ├── xui_client.py
│   ├── logger_setup.py
│   └── utils.py
├── config/             # Configuration
│   └── config.example.json
├── docker/             # Docker setup
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── .env.example
└── requirements.txt    # Dependencies

Management

# View logs
docker-compose logs -f

# Restart bot
docker-compose restart

# Stop bot
docker-compose down

# Update and restart
docker-compose pull && docker-compose up -d

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
config		config
docker		docker
src		src
LICENSE		LICENSE
README.md		README.md
README_new.md		README_new.md
requirements.txt		requirements.txt

License

noobconner21/3XUI-Panel-Client-Management-Telegram-Bot

Folders and files

Latest commit

History

Repository files navigation

🤖 3XUI Panel Client Management Bot

✨ Features

🎯 Core Client Management

📊 Advanced Features

🛡️ Security & Control

🚀 Quick Start

🐳 Docker Deployment (Recommended)

🐍 Manual Installation

🔧 Configuration

📋 Environment Setup

🔑 Getting Your Credentials

📖 Commands

🎮 Bot Commands

🛠️ Advanced Usage

🛠️ Installation

🐳 Docker Installation (Recommended)

📋 Prerequisites

🚀 Step-by-Step Setup

🐍 Manual Installation

📋 Prerequisites

🚀 Step-by-Step Setup

🏗️ Project Structure

🤝 Contributing

🔧 Development Setup

📝 Contribution Guidelines

🆘 Troubleshooting

🐛 Common Issues

📋 Viewing Logs

🔧 Debug Mode

❓ FAQ

📄 License

💬 Support & Community

📞 Getting Help

🤝 Community Guidelines

🚀 Roadmap

📅 Planned Features

🎯 Current Focus

🙏 Acknowledgments

📈 Stats

Bot Commands

User Commands

Admin Commands

Project Structure

Management

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages