🤖 WGDashboard Erinys (Telegram Bot)

🇬🇧 English | 🇪🇸 Español

---

Professional Telegram bot to manage and monitor WireGuard through the WGDashboard API. Allows administrators to manage peers, monitor server status, and execute administrative actions directly from Telegram.

✨ Main Features

Administrators

• 📡 Configuration Management: View all WireGuard configurations
• 👥 Peer Management: Create, delete, view details, and monitor peers
• 🔒 Restrictions: Restrict/allow access for specific peers
• 🧹 Traffic Cleanup: Reset data counters for peers
• ⏰ Schedule Jobs: Create scheduled tasks (data limits and expiration dates)
• 🖥️ System Status: Monitor CPU, memory, disks, and interfaces
• 📊 Statistics: View detailed system information
• 👷 Operator Supervision: Monitor authorized operator activity
• 🌐 Multi-language: Support for Spanish and English

Operators

• ➕ Create Temporary Peers: Generate peers with automatic limits
• 📥 Download Config: Get .conf file for the new peer
• 🌐 Change Language: Select between Spanish and English
• ⏳ Automatic Limits: 1 GB data and 24 hours duration per peer

📁 Project Structure

TGBot-saveOK/
├── main.py                    # Bot entry point
├── config.py                  # Configuration and environment variables
├── handlers.py                # Command and callback handlers (4100+ lines)
├── keyboards.py               # Telegram inline keyboards
├── i18n.py                    # Multi-language translation system
├── operators.py               # Authorized operator control
├── utils.py                   # Utility functions
├── wg_api.py                  # WGDashboard API client
├── setup_logging.py           # Logging configuration
├── .env                       # Environment variables (DO NOT commit)
├── requirements.txt           # Project dependencies
├── README.md                  # This file
├── locales/
│   ├── es.json                # Spanish translation
│   └── en.json                # English translation
└── info/
    ├── resumen.md             # Technical documentation
    ├── CAMBIOS_REALIZADOS.md  # Change history
    └── IMPLEMENTACION_*.md    # Feature documentation

🛠️ Prerequisites

Operating System

• Linux (Ubuntu 22.04 LTS or higher recommended)
• Python 3.10 or higher
• pip (Python Package Manager)

External Dependencies

• WireGuard: Installed and configured on the server
• WGDashboard: Running and accessible via API
• Telegram Bot: Created with @BotFather

📦 Installation Step by Step

1. Clone or download the project

git clone https://github.com/WGDashboard/WGErinys
cd WGErinys

2. Create virtual environment (recommended)

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment variables

Create .env file in the project root:

# ===== TELEGRAM =====
TELEGRAM_BOT_TOKEN=your_token_here  # Get from @BotFather on Telegram

# ===== WGDASHBOARD API =====
WG_API_BASE_URL=https://your-domain.com/api  # Base URL of the API
WG_API_KEY=your_api_key_here                 # WGDashboard API Key
WG_API_PREFIX=wg                             # API prefix (if applicable)
API_TIMEOUT=10                               # Timeout in seconds

# ===== LOGGING =====
LOG_FILE=wg_bot.log                          # Log file
LOG_LEVEL=INFO                               # DEBUG, INFO, WARNING, ERROR

# ===== ACCESS =====
ALLOWED_USERS=123456789,987654321            # Authorized Telegram IDs
ROLE_ADMIN=admin                             # Administrator role
ROLE_OPERATOR=operator                       # Operator role
ADMIN_IDS=123456789                          # IDs that are administrators
OPERATOR_IDS=987654321,111222333             # IDs that are operators

# ===== OPERATOR LIMITS =====
OPERATOR_DATA_LIMIT_GB=1                     # GB per created peer
OPERATOR_TIME_LIMIT_HOURS=24                 # Hours of peer duration

5. Configure authorized users

Edit config.py and add Telegram IDs:

# Authorized IDs to use the bot
ALLOWED_USERS = [
    123456789,  # Admin 1
    987654321,  # Admin 2
    111222333,  # Operator 1
]

# Role configuration
ADMIN_USERS = [123456789, 987654321]
OPERATOR_USERS = [111222333]

# Operator limits
OPERATOR_DATA_LIMIT_GB = 1          # 1 GB per peer
OPERATOR_TIME_LIMIT_HOURS = 24      # 24 hours duration

To get your Telegram ID:

1. Open @userinfobot on Telegram
2. The bot will show your ID

🚀 Running the Bot

Local Development

# With virtual environment activated
python main.py

Production on VPS

Option 1: Using systemd (recommended)

Create service file:

sudo nano /etc/systemd/system/wgbot.service

File content:

[Unit]
Description=WGDashboard Telegram Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=wgbot
Group=wgbot
WorkingDirectory=/home/wgbot/TGBot-saveOK
Environment="PATH=/home/wgbot/TGBot-saveOK/.venv/bin"
ExecStart=/home/wgbot/TGBot-saveOK/.venv/bin/python main.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Enable and start the service:

# Reload systemd
sudo systemctl daemon-reload

# Enable to start automatically
sudo systemctl enable wgbot

# Start the bot
sudo systemctl start wgbot

# Check status
sudo systemctl status wgbot

# View logs in real-time
sudo journalctl -u wgbot -f

# Stop
sudo systemctl stop wgbot

# Restart
sudo systemctl restart wgbot

Option 2: Using Docker (if available)

# Build image
docker build . -f docker/Dockerfile -t wgerinys:latest

# Run container
docker run -d --name wgerinys --env-file .env wgerinys:latest

Option 3: Using tmux (simple)

# Install tmux
sudo apt-get install tmux

# Create session
tmux new-session -d -s wgbot -c /path/to/bot python main.py

# View sessions
tmux list-sessions

# Connect to session
tmux attach-session -t wgbot

# Disconnect (Ctrl+b, then d)

📋 Available Commands

For Administrators

Command	Description
/start	Start bot and show main menu
/help	Show help and available commands
/stats	Show system statistics
/configs	List all WireGuard configurations

Functions via menu:

• 📡 Configurations - Manage all configs
• 👥 Peers - View, create, delete, list
• 🖥️ System Status - CPU, RAM, disks, network
• ⚡ Protocols - View enabled protocols
• 👷 Operators - View operator activity
• 🌐 Language - Switch between Spanish and English

For Operators

Command	Description
/start	Show menu to create peers
/help	Information about limits and functions

Functions:

• ➕ Create Peer - Generate new temporary peer
• 📥 Download - Get configuration file
• 🌐 Language - Change language

🔐 Security and Access Control

Permission Levels

Administrator (full access)

• All bot functions
• Full peer management
• Access to statistics
• Operator supervision

Operator (limited access)

• Only create temporary peers
• Download configuration of created peers
• No access to existing peer management

Unauthorized (no access)

• Bot rejects any command
• Error message: "Access restricted"

Security Best Practices

1. WGDashboard API Key

   • Use environment variables .env
   • Never commit .env to git
   • Add to .gitignore

2. Telegram Bot Token

   • Keep in .env
   • Change if exposed
   • Use webhook restrictions if possible

3. Server Access

   • Active firewall
   • SSH with public keys
   • Change default SSH port
   • Monitor logs regularly

4. WGDashboard

   • Behind reverse proxy (nginx)
   • HTTPS mandatory
   • Strong authentication
   • Regular backups

📊 Detailed Features

Peer Management

Create Peer

• Unique name
• Automatic IP
• WireGuard keys generated
• .conf file sent directly
• Automatic limits applied

Peer Details

• Network information (IP, endpoint, DNS)
• Connection status (connected/disconnected)
• Traffic (sent, received, cumulative)
• Keys (public, pre-shared)
• Scheduled jobs
• Shared links

Restrictions

• Restrict peer (blocks connection)
• Allow access (removes restriction)
• Pagination
• Available filters

Schedule Jobs

Scheduled jobs allow:

• Data Limit: Restrict when reaching X GB
• Expiration Date: Auto restrict on date X
• Create/delete jobs on the fly
• Full task management

System Statistics

Monitor in real-time:

• 💻 CPU usage (%)
• 🧠 RAM usage (% and details)
• 💾 Disk usage (main drives)
• 📡 Network interfaces (traffic)
• 🔗 WireGuard interfaces

🌐 Multi-language Support

The bot automatically supports:

• 🇪🇸 Spanish - Complete Spanish interface
• 🇬🇧 English - Complete English interface

Users can change language from the menu at any time. Preferences are automatically saved.

📝 Logs and Debugging

View logs in real-time

# If using systemd
sudo journalctl -u wgbot -f

# If running directly
tail -f wg_bot.log

Log Levels

DEBUG   - Detailed information for debugging
INFO    - Important events
WARNING - Warnings (potential issues)
ERROR   - Errors affecting functionality

Configure log level

Edit .env:

LOG_LEVEL=DEBUG  # For more detail in development

🆘 Troubleshooting

Bot not responding

# Check if it's running
sudo systemctl status wgbot

# View logs
sudo journalctl -u wgbot -n 50

# Restart
sudo systemctl restart wgbot

Error: "Cannot connect to API"

• Verify WG_API_BASE_URL in .env
• Verify WG_API_KEY is correct
• Test connectivity: curl https://your-url/api/handshake
• Check firewall/proxy allows connection

Error: "Invalid Telegram token"

• Verify TELEGRAM_BOT_TOKEN in .env
• Create new token with @BotFather
• Check for whitespace

Bot doesn't see my changes

# Restart to load changes
sudo systemctl restart wgbot

# Or if using tmux
tmux send-keys -t wgbot "C-c"
python main.py

📚 Additional Documentation

• info/resumen.md - Technical API analysis
• info/CAMBIOS_REALIZADOS.md - Change history
• info/IMPLEMENTACION_*.md - Feature details

🤝 Contributions

Contributions are welcome. Please:

1. Fork the project
2. Create a branch for your feature (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

👨‍💻 Author

Jorge Elián Martinez Perdomo

Professional Telegram bot for WireGuard administration using WGDashboard

• GitHub: @jemartinezp1994
• Telegram: @jemp01K
• Discord: ff_c3r0

---

Last Updated: January 11, 2026 Version: 2.0