3x-uiTelegram Bot
Connect a Telegram bot to 3x-ui for commands, periodic reports, event alerts (login, CPU, node up/down), backups, and client self-service.
3x-ui can drive a Telegram bot for monitoring, alerts, backups, and remote management. Admins get full control; regular users (linked by Telegram ID) can check their own usage and links.
Looking for news and community support? Join the official Telegram channel @XrayUI. That's separate from the bot below, which you run yourself to manage your own panel.
Set it up
Create a bot
Message @BotFather, send /newbot, and copy the bot
token.
Find your Telegram ID
Get your numeric Telegram user ID (the bot's own /id command reports it once
connected). This is your admin ID.
Configure the panel
In Panel Settings, enable the Telegram bot and set the token and admin chat ID(s) (comma-separated). Save, then message your bot.
Validate your token, admin IDs, and report schedule before pasting them into the panel:
Telegram bot setup helper
Validate your bot token, admin IDs, and report schedule, then copy the panel settings.
Valid (macro)
tgBotEnable = true
tgBotToken = <token>
tgBotChatId = <admin ids>
tgRunTime = @dailyhttps://api.telegram.org/bot<token>Commands
These appear in the Telegram command menu: /start, /help, /status, /id.
Additional commands:
| Command | Who | Action |
|---|---|---|
/start | anyone | Greeting and the menu of inline buttons; an unlinked account gets only its Telegram ID |
/help | both | The menu of inline buttons |
/status | both | Confirm the bot is alive |
/id | anyone | Show your Telegram numeric ID |
/usage <arg> | both | Admins search clients; users look up their own usage |
/inbound <remark> | admin | Show an inbound's details |
/restart | admin | Restart Xray |
A user is a Telegram account linked to at least one client. Any other account
can run only /start and /id; the bot ignores its other commands and
button taps. To link a customer, tap Invite Link on the client's card in the bot and
send them the t.me link: the first account to open it is linked to every
client that shares that Subscription ID. The Subscription ID is the invite code,
so keep it long and random. Each account gets five claim attempts an hour, and
admins are notified when one runs out.
Admins also get inline-button flows for server usage, sorted traffic reports, resetting traffic, DB backups, ban logs, listing inbounds/clients, online clients, "depleting soon", and a full add-client wizard. Regular users get buttons for their own usage, subscription links, individual links, and QR codes.
Reports & alerts
-
Periodic report — on the
tgRunTimeschedule (default@daily), the bot sends admins server usage (host, versions, uptime, load, memory, online clients, traffic), a list of exhausted/expiring clients, and — iftgBotBackupis on — a database + Xray config backup. Clients linked by Telegram ID get their own expiry/quota warnings. -
Event alerts — selected by
tgEnabledEvents(defaultlogin.attempt,cpu.high):Event When login.attemptA panel login succeeds or fails (with IP and username) cpu.highCPU exceeds tgCpupercent (default 80)memory.highMemory exceeds tgMemorypercent (default 80)xray.crashXray-core crashes outbound.down/outbound.upAn outbound goes down / recovers node.down/node.upA node goes offline / comes back
The warning lead times come from expireDiff (days before expiry) and
trafficDiff (GB of quota remaining); both default to 0 (off).
Settings
| Setting | Default | Meaning |
|---|---|---|
tgBotEnable | false | Master on/off. |
tgBotToken | (secret) | Bot API token. |
tgBotChatId | (none) | Comma-separated admin Telegram IDs. |
tgBotProxy | (none) | socks5://, http://, or https:// proxy. |
tgBotAPIServer | (default) | Custom Telegram Bot API server. |
tgRunTime | @daily | Report schedule (cron / @daily / @every …). |
tgBotBackup | false | Attach a DB backup to the periodic report. |
tgCpu / tgMemory | 80 / 80 | CPU / memory alert thresholds (percent). |
tgLang | en-US | Bot language. |
tgEnabledEvents | login.attempt,cpu.high | Which events to deliver. |
The bot token controls your bot — keep it secret and only add trusted admin chat IDs. Login alerts never include passwords.
Email (SMTP) notifications mirror the same events (smtpEnabledEvents) if you'd
rather receive alerts by email — configure SMTP in Panel Settings.