09. Telegram Bot Architecture & Management Protocol

Tachyon includes an embedded, high-performance Telegram management bot written entirely in ucode (service/telegram.uc).

1. Architectural Highlights

graph LR
    User[Telegram Client] -->|Encrypted HTTPS| TGAPI[Telegram Bot API Servers]
    TGAPI -->|Long Polling: getUpdates| Daemon[Tachyon telegram.uc Daemon]
    
    Daemon --> Auth{Admin Chat ID Match?}
    Auth -->|No| Reject[Silent Ignore / Warning]
    Auth -->|Yes| Router[Command & Callback Dispatcher]
    
    Router -->|/doctor, /ai_doctor| AIDoc[AI Doctor Engine]
    Router -->|/server, /switch| SrvMgr[Server Manager]
    Router -->|/restart| SvcLife[Service Lifecycle]
    Router -->|/status| StateRep[State Assembler]

No Public IP or Port Forwarding Required: Uses outbound long-polling (getUpdates with 30s timeout) to securely communicate through NAT/firewalls.
Zero Overhead Memory Footprint: Runs as a lightweight ucode process consuming under 2 MB RAM.
Role-Based Access Control: Rejects any commands from chat IDs not explicitly listed in UCI option telegram_chat_id.

2. Command Set Reference

Command	Arguments	Action
`/start`	—	Displays main welcome card and interactive control keyboard.
`/status`	—	Returns real-time health card: uptime, active server, RAM usage, ping RTT.
`/doctor`	—	Executes Local Rule Doctor and returns offline diagnostic report.
`/ai_doctor`	—	Invokes AI Doctor with LLM reasoning and returns diagnosis + fix buttons.
`/fix`	`<fix_code>`	Applies specific automated repair code (e.g. `/fix clear_dns_cache`).
`/server`	—	Opens interactive server selector with inline pagination and RTT pings.
`/rules`	—	Shows active routing rules with 1-click toggle switches.
`/restart`	`[service]`	Restarts sing-box, dnsmasq, watchdog, or entire network stack.
`/backup`	—	Sends latest atomic configuration backup directly to Telegram chat.

3. Inline Keyboard & Callback Query Protocol

The bot uses dynamic inline keyboards (InlineKeyboardMarkup) for single-tap actions without typing commands.

3.1. Callback Data Scheme

Callbacks follow a structured token format: action:target:param

srv:select:node_1        # Switch active proxy server to node_1
rule:toggle:youtube      # Toggle routing rule 'youtube' on/off
fix:apply:clear_dns_cache# Execute repair code 'clear_dns_cache'
page:srv:2              # Navigate to page 2 of server list

3.2. Example: Server Switcher Response

{
  "chat_id": 123456789,
  "text": "⚡ <b>Выберите активный сервер:</b>\nТекущий: <i>🇩🇪 Frankfurt VLESS (18 ms)</i>",
  "parse_mode": "HTML",
  "reply_markup": {
    "inline_keyboard": [
      [
        {"text": "🇩🇪 Frankfurt (18 ms) ✅", "callback_data": "srv:select:de_1"},
        {"text": "🇳🇱 Amsterdam (24 ms)", "callback_data": "srv:select:nl_1"}
      ],
      [
        {"text": "🇫🇮 Helsinki (31 ms)", "callback_data": "srv:select:fi_1"},
        {"text": "🇺🇸 New York (95 ms)", "callback_data": "srv:select:us_1"}
      ],
      [
        {"text": "🔄 Замерить пинг", "callback_data": "srv:ping:all"},
        {"text": "🩺 Запустить Доктора", "callback_data": "cmd:doctor"}
      ]
    ]
  }
}

4. Configuration via CLI

# Set Bot Token
uci set tachyon.settings.enable_telegram='1'
uci set tachyon.settings.telegram_token='123456789:ABCdefGHIjklMNOpqrsTUVwxyz'

# Set Authorized Chat ID(s)
uci set tachyon.settings.telegram_chat_id='123456789'

# Commit and restart service
uci commit tachyon
/etc/init.d/tachyon restart

3.7 KiB Raw Blame History