Home

XyroSupportBot Wiki

Overview

XyroSupportBot is a comprehensive Telegram customer support bot built with Pyrogram that provides advanced ticket management, token-based activation system, channel button integration, business hours management, and enterprise-grade features. It's designed to help businesses and communities manage customer support efficiently through Telegram groups and channels.

Key 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
Business Hours Awareness: Respect business operating hours for automated responses
Secure Paste Service: Integration with PrivateBin for secure text sharing
Advanced Rate Limiting: Configurable anti-spam protection with business hours awareness
Multi-language Support: Translation capabilities with language detection
File Security: VirusTotal integration for security scanning
Statistics & Analytics: Comprehensive usage tracking and reporting

Architecture

Technology Stack

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

Project Structure

XyroSupportBot/
├── XyroSupport/
│   ├── __init__.py          # Configuration and constants
│   ├── __main__.py          # Application entry point
│   ├── database/            # Database models and operations
│   │   ├── channel.py       # Channel button management
│   │   ├── users.py         # User management
│   │   ├── tickets.py       # Ticket system
│   │   └── ...
│   ├── helpers/             # Utility functions and decorators
│   └── modules/             # Bot command handlers
│       ├── button.py        # Channel button management
│       ├── business.py      # Business hours management
│       ├── paste.py         # PrivateBin integration
│       └── ...
├── nix/                     # Nix build configurations
├── Dockerfile               # Docker deployment
└── config.yml               # Main configuration file

Installation

Prerequisites

Python 3.12 or higher
Telegram Bot API credentials
Database (PostgreSQL recommended for production)
PrivateBin instance (for paste functionality)

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 Deployment

Build the Docker image:
```
docker build -t xyrosupport .
```

Run the container:

docker run -d --name xyrosupport \
  -v $(pwd)/config.yml:/app/config.yml \
  xyrosupport

Method 3: Poetry Development Setup

Install dependencies:
```
poetry install
```
Activate virtual environment:
```
poetry shell
```
Run the bot:
```
python -m XyroSupport
```

Configuration

1. Create Configuration File

Copy sample_config.yml to config.yml and fill in your details:

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
  topic_id: 12345                     # Support topic ID (optional)
  bot_token: "123456:ABC-DEF..."      # Bot token from @BotFather
  owner_id: 123456789                 # Your Telegram user ID
  sudo_users:                         # Admin users
    - 123456789
    - 987654321
  support_bot: "@your_support_bot"    # Support bot username
  drop_updates: true                  # Skip pending updates

database:
  schema: "postgresql://user:pass@localhost/dbname"  # Database URL

misc:
  vt_api_key: "your_virustotal_api"    # VirusTotal API key (optional)
  disable:                             # Disabled modules
    - module_name

enterprise:
  max_chat_allowed: 20                 # Maximum channels for enterprise
  inactive_chat_kick_timer: 86400      # 24 hours in seconds
  business_name: "Your Business Name"  # Display name for business
  private_bin_url: "https://paste.example.com"  # PrivateBin instance

value_limits:
  max_free_assigned_tickets: 5
  max_free_active_tickets: 8
  max_free_ticket_per_user: 1

rate_limits:
  min_num_messages: 3
  min_val_duration: 10.0
  max_num_messages: 5
  max_val_duration: 20.0

links:
  privacy: "https://your-site.com/privacy"
  terms: "https://your-site.com/terms"

2. Database Setup

PostgreSQL (Recommended)

CREATE DATABASE xyrosupport;
CREATE USER xyrosupport WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE xyrosupport TO xyrosupport;

SQLite (Development)

database:
  schema: "sqlite:///xyrosupport.db"

3. PrivateBin Setup (Optional)

For paste functionality, set up a PrivateBin instance and configure the URL in the enterprise section.

Token Generation and Activation

Automatic Token Generation

When you first run the bot, it automatically generates a unique activation token for the bot owner:

Token Generation Process:
- Bot creates a UUID7-based token automatically on first startup
- Token is stored in the subscriptions database table
- Only the bot owner (defined in config.yml) gets an automatic token
Getting Your Token:
- Check the bot logs when it first starts
- Use /subscription command if you're the bot owner
- The token will be displayed in the format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Token Security:
- Tokens are unique UUID7 strings
- Store tokens securely and share only with trusted users
- You can regenerate tokens if needed (owner only)

Group Activation

Use your activation token to enable bot features in Telegram groups:

Basic Setup:
- Add the bot to your Telegram group as an administrator
- Send /activate <your_token> in the group
- The bot will confirm activation and enable features
Feature Levels:
- Without Token: Basic functionality (1 channel button, 8 active tickets, 5 assigned tickets)
- With Token: Full functionality (up to 20 channel buttons, unlimited tickets, media support, business hours)
Managing Activations:
- Use /subscription to view all your tokens and active groups
- Use /deactivate <token> to remove features from a group
- Each token can activate multiple groups (configurable via max_chat_allowed)

Usage

Bot Commands

User Commands

/start - Start the bot and see main menu
/help - Display help information
/new or /ticket - Create a new support ticket
/close - Close your current ticket
/feedback #123 - Submit feedback for ticket #123
/ping - Check bot response time

Admin Commands

/admin - Access admin panel
/settings - Configure group settings
/channel_button or /button - Manage channel buttons
/sethours or /setbusinesshours - Set business operating hours
/hours or /businesshours - View current business hours
/paste - Create secure paste using PrivateBin
/faq add/remove/list - Manage FAQs
/stats - View usage statistics
/activate <token> - Activate bot features in current group using token
/deactivate <token> - Deactivate bot features from current group
/subscription - View your activation tokens

Channel Commands

/register_channel <code> - Register a channel with verification code
/register_support <url> - Register support URL for channel buttons

Sudo User Commands

/channel_limit <chat_id> <count> - Set custom channel limits
/broadcast - Send announcements

Channel Button System

The channel button system allows you to add "Create a Ticket" buttons to your Telegram channels automatically:

Setup Process:
- Use /channel_button in your support group
- Click "Add a New Channel"
- Add the bot to your target channel with admin permissions
- Send /register_channel <code> in the channel
- Send /register_support <url> with a valid support URL
- Bot automatically adds buttons to all channel posts
Requirements:
- Bot must be admin in the channel
- Bot needs "Delete Messages" and "Edit Messages" permissions
- Valid support URL generated by /gentoken command
Features:
- Automatic button addition to all posts
- Secure verification system
- Automatic cleanup of unverified channels (24 hours)
- Support for multiple channels per group

Token-Based Activation System

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

Token Generation:
- When the bot first runs, it automatically generates a unique activation token for the bot owner
- The token is generated using UUID7 for uniqueness
- Owner can view tokens using /subscription command
Activation Process:
- Use /activate <token> to enable bot features in a group
- Use /deactivate <token> to disable features from a group
- Use /subscription to view your activation tokens
- Tokens can be used in multiple groups (with configurable limits)
Feature Comparison:
- Without Token: 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 business operating hours to provide better customer service:

Setting Business Hours:
- Use /sethours command
- Select your timezone from the list
- Choose business days
- Set opening and closing times
- Confirm settings
Features:
- Timezone-aware scheduling
- Different hours for different days
- Automatic business hours detection
- Integration with automated responses

Ticket Management (`tickets.py`)

Advanced ticket creation and management
Business hours awareness
Automatic ticket assignment
Status tracking and updates

PrivateBin Integration (`paste.py`)

Secure paste creation for sensitive data
Integration with PrivateBin instances
File type validation and size limits
Automatic cleanup

Token Activation System (`subscription.py`)

Token-based feature activation
Multi-group activation management
Feature control via tokens
Automatic token generation for owner

Utility Modules

File Scanner (`scanner.py`)

VirusTotal integration for security
Automatic threat detection
File validation and scanning

Privacy (`privacy.py`)

GDPR compliance features
Data export and deletion
Privacy policy management

Rate Limiting (`limiter.py`)

Advanced rate limiting with business hours
Configurable limits per group
Anti-spam protection

Database Schema

Core Tables

ChannelButtons

Channel verification and management
Support URL configuration
Verification status tracking
Message ID management for cleanup

Users

User information and preferences
Ticket history and statistics
Token activation status

Tickets

Ticket metadata and status
Business hours tracking
Assignment and resolution data

Groups

Group configurations and settings
Business hours and timezone
Channel limits and permissions

API Integration

Telegram Bot API

Full Pyrogram integration
Channel management capabilities
Advanced message handling
Inline query support

External Services

VirusTotal: File security scanning
PrivateBin: Secure paste service
Translation APIs: Multi-language support

Deployment

Production Deployment

Docker (Recommended)

# Multi-stage build for optimal image size
FROM python:3.12-alpine AS builder
# ... build stages ...
FROM python:3.12-alpine AS runtime
# ... runtime configuration ...

Docker Compose

version: '3.8'
services:
  xyrosupport:
    build: .
    environment:
      - CONFIG_PATH=/app/config.yml
    volumes:
      - ./config.yml:/app/config.yml
    depends_on:
      - postgres
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: xyrosupport
      POSTGRES_USER: xyrosupport
      POSTGRES_PASSWORD: password

Systemd Service

[Unit]
Description=XyroSupportBot
After=network.target

[Service]
Type=simple
User=xyrosupport
WorkingDirectory=/opt/xyrosupport
ExecStart=/opt/xyrosupport/.venv/bin/python -m XyroSupport
Restart=always

[Install]
WantedBy=multi-user.target

Environment Variables

export CONFIG_PATH="/path/to/config.yml"
export LOG_LEVEL="INFO"
export DATABASE_URL="postgresql://..."
export PRIVATE_BIN_URL="https://paste.example.com"

Security Considerations

Data Protection

All sensitive data encrypted at rest
API keys stored securely
User data anonymization options
GDPR compliance features
Secure paste functionality with PrivateBin

Access Control

Role-based permissions system
Sudo user hierarchy
Group-specific settings
Channel verification system
Business hours access control

Channel Security

Unique code verification
Permission validation
Automatic cleanup mechanisms
Secure URL validation

Troubleshooting

Common Issues

Channel Button Not Working

Verify bot has admin permissions in channel
Check bot has "Delete Messages" and "Edit Messages" permissions
Ensure channel is properly verified
Check support URL is valid and from bot

Business Hours Not Respected

Verify timezone is correctly set
Check business hours configuration
Ensure scheduler is running
Review log files for errors

PrivateBin Integration Issues

Verify PrivateBin URL is accessible
Check API endpoint compatibility
Ensure file size limits are respected
Test with different file types

Database Connection Issues

Verify database URL format
Check database server status
Confirm credentials and permissions
Test network connectivity

Debug Mode

Enable debug logging by setting:

logging.getLogger("[XyroSupport]").setLevel(logging.DEBUG)

Enterprise Features

Advanced Channel Management

Custom channel limits per group
Bulk channel operations
Advanced verification workflows
Channel analytics and reporting

Business Branding

Custom business name display
Branded support URLs
Custom business hours
Enterprise-level support

Advanced Security

Enhanced verification systems
Custom security policies
Advanced audit logging
Compliance features

Contributing

Development Setup

Fork the repository
Create development environment:
```
nix develop
```
Make your changes
Run tests:
```
poetry run pytest
```
Submit pull request

Code Style

Follow PEP 8 guidelines
Use type hints consistently
Add comprehensive docstrings
Include unit tests for new features
Follow the existing module structure

License

This project is licensed under the GPLv3 License. See the LICENSE file for details.

Support

For support:

Check this wiki first
Search existing issues on GitHub
Create new issue with detailed information

Changelog

Version 0.1.0

Initial release as XyroSupportBot
Channel button integration system
Business hours management
PrivateBin integration
Enterprise features and customization
Advanced security and verification systems
Token-based activation system
Docker and Nix deployment support

Last updated: November 2025