XyroSupportBot

A comprehensive Telegram customer support bot built with Pyrogram that provides advanced ticket management, channel button integration, business hours management, and enterprise-grade features.

✨ Features

Core Functionality

• 🎫 Advanced Ticket Management: Create, assign, and track support tickets with sophisticated routing
• 🔗 Channel Button Integration: Add support buttons to Telegram channels automatically
• 🎟️ Token-Based Activation: Generate activation tokens to enable bot features in groups
• 🕐 Business Hours Management: Set operating hours and timezone-aware responses
• 🔒 PrivateBin Integration: Secure paste functionality for sensitive data
• 🏢 Enterprise Features: Advanced channel management, custom limits, and business branding

Advanced Features

• 🛡️ Automated Channel Verification: Secure channel linking with verification system
• ⏰ Scheduled Cleanup: Automatic removal of unverified channels after 24 hours
• 🌍 Multi-language Support: Translation capabilities with language detection
• 🦠 File Security: VirusTotal integration for security scanning
• 📊 Statistics & Analytics: Comprehensive usage tracking and reporting
• 🚦 Advanced Rate Limiting: Configurable anti-spam protection with business hours awareness

🚀 Quick Start

Prerequisites

• Python 3.12 or higher
• Telegram Bot API credentials
• Database (PostgreSQL recommended for production)

Installation

Method 1: Nix Flakes (Recommended)

# Clone the repository
git clone https://github.com/Atlas-Projects/XyroSupportBot
cd XyroSupportBot

# Install the bot
nix profile install .

# Run the bot
XyroSupport

Method 2: Docker

# Build and run with Docker Compose
docker-compose up -d

Method 3: Poetry (Development)

# Install dependencies
poetry install

# Activate virtual environment
poetry shell

# Run the bot
python -m XyroSupport

⚙️ Configuration

1. Copy the sample configuration:

cp sample_config.yml config.yml

2. Edit config.yml with your settings:

telegram:
  api_id: 12345678                    # Get from my.telegram.org
  api_hash: "your_api_hash"           # Get from my.telegram.org
  group_id: -1001234567890            # Your support group ID
  bot_token: "123456:ABC-DEF..."      # Bot token from @BotFather
  owner_id: 123456789                 # Your Telegram user ID

database:
  schema: "postgresql://user:pass@localhost/dbname"

enterprise:
  max_chat_allowed: 20                 # Maximum channels for premium
  business_name: "Your Business Name"
  private_bin_url: "https://paste.example.com"

3. Set up your database and run the bot.

🎟️ Bot Activation

When you first run the bot, it automatically generates a unique activation token for the bot owner. Use this token to activate the bot in your Telegram groups:

Getting Your Token

1. Run the bot for the first time
2. Check the bot logs or use /subscription command (if you're the owner)
3. Copy your activation token

Activating in Groups

1. Add the bot to your Telegram group as an administrator
2. Send /activate <your_token> in the group
3. The bot will be activated and ready to use

Managing Activations

• Use /subscription to view your activation tokens
• Use /deactivate <token> to deactivate from a group
• Each token can be used in multiple groups (with configurable limits)

📖 Documentation

📚 Full Wiki Documentation

The comprehensive wiki covers:

• 📋 Complete Feature Overview
• 🔧 Installation & Configuration Guide
• 💼 Channel Button System Setup
• 🕐 Business Hours Configuration
• 🎟️ Token Activation Guide
• 🐳 Deployment Instructions
• 🔒 Security Considerations
• 🛠️ Troubleshooting Guide

🎯 Key Features Overview

Channel Button System

Automatically add "Create a Ticket" buttons to your Telegram channels:

• Secure verification system with unique codes
• Automatic button addition to all posts
• Support for multiple channels per group
• Automatic cleanup of unverified channels

Token-Based Activation

The bot uses a token system to enable features in groups:

• Default Limits: 1 channel button, 8 active tickets, 5 assigned tickets
• With Token: Up to 20 channel buttons, unlimited tickets, media support, business hours

Business Hours Management

Set your operating hours for better customer service:

• Timezone-aware scheduling
• Different hours for different days
• Integration with automated responses

🏗️ Architecture

• Language: Python 3.12+
• Framework: Pyrogram (Telegram Bot API)
• Database: SQLAlchemy 2.0 with Alembic migrations
• Task Scheduling: APScheduler
• Package Management: Poetry
• Deployment: Nix flakes and Docker support

🐳 Docker Deployment

# Build the image
docker build -t xyrosupport .

# Run with environment variables
docker run -d --name xyrosupport \
  -v $(pwd)/config.yml:/app/config.yml \
  xyrosupport

🔧 Systemd Service

Create a user systemd service at ~/.config/systemd/user/xyrosupport@.service:

[Unit]
Description=XyroSupport Service for %i
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/instances/%i
ExecStart=bash -c "sleep 5 && /path/to/.nix-profile/bin/XyroSupport --config /path/to/instances/%i/config.yml"
Restart=on-failure
Environment=SERVICE_NAME=xyrosupport@%i

[Install]
WantedBy=default.target

Enable and start:

systemctl --user daemon-reload
systemctl --user enable xyrosupport@your-instance
systemctl --user start xyrosupport@your-instance

🤝 Contributing

We welcome contributions! Please see our contributing guidelines in the wiki.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

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

🆘 Support

• 📚 Documentation: Check the Wiki first
• 🐛 Issues: Report bugs on GitHub

🔗 Links

• 📖 Full Wiki Documentation
• 🐳 Docker Hub
• 📦 PyPI Package

---

XyroSupportBot - Professional customer support made simple on Telegram.