mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-10-25 15:25:01 +03:00
Tuyến Trần
a403faee23
Admins who run the bot in a forum supergroup got every notification in the General topic. An admin chat ID may now carry a topic, chatId:topicId, and the bot's admin messages and reports go to that topic. Repeated chats collapse into one entry and a second, different topic for the same chat is rejected, in the panel and in the docs setup helper alike. The chat ID hint in every locale and the English, Persian, Russian and Chinese guides describe the form.
127 lines
6.0 KiB
Plaintext
127 lines
6.0 KiB
Plaintext
---
|
|
title: Telegram Bot
|
|
description: Connect a Telegram bot to 3x-ui for commands, periodic reports, event alerts (login, CPU, node up/down), backups, and client self-service.
|
|
icon: Send
|
|
---
|
|
|
|
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.
|
|
|
|
<Callout type="info">
|
|
Looking for news and community support? Join the official Telegram channel
|
|
[@XrayUI](https://t.me/XrayUI). That's separate from the bot below, which you
|
|
run yourself to manage your own panel.
|
|
</Callout>
|
|
|
|
## Set it up
|
|
|
|
<Steps>
|
|
|
|
<Step>
|
|
### Create a bot
|
|
|
|
Message [@BotFather](https://t.me/BotFather), send `/newbot`, and copy the **bot
|
|
token**.
|
|
</Step>
|
|
|
|
<Step>
|
|
### 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.
|
|
</Step>
|
|
|
|
<Step>
|
|
### 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.
|
|
|
|
To send notifications into a specific topic of a forum supergroup, append the
|
|
topic ID after a colon, e.g. `-1001234567890:42`. The topic ID is the number
|
|
after the chat in a topic message link (`https://t.me/c/1234567890/42/…`). Leave
|
|
the topic off (or use `1`) for the General topic.
|
|
</Step>
|
|
|
|
</Steps>
|
|
|
|
Validate your token, admin IDs, and report schedule before pasting them into the
|
|
panel:
|
|
|
|
<TelegramSetupHelper />
|
|
|
|
## 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 `tgRunTime` schedule (default `@daily`), the bot
|
|
sends admins server usage (host, versions, uptime, load, memory, online
|
|
clients, traffic), a list of exhausted/expiring clients, and — if
|
|
`tgBotBackup` is on — a database + Xray config backup. Clients linked by
|
|
Telegram ID get their own expiry/quota warnings.
|
|
- **Event alerts** — selected by `tgEnabledEvents` (default `login.attempt,cpu.high`):
|
|
|
|
| Event | When |
|
|
| --------------- | ------------------------------------------------------- |
|
|
| `login.attempt` | A panel login succeeds or fails (with IP and username) |
|
|
| `cpu.high` | CPU exceeds `tgCpu` percent (default 80) |
|
|
| `memory.high` | Memory exceeds `tgMemory` percent (default 80) |
|
|
| `xray.crash` | Xray-core crashes |
|
|
| `outbound.down` / `outbound.up` | An outbound goes down / recovers |
|
|
| `node.down` / `node.up` | A 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; `chatId:topicId` targets a forum topic. |
|
|
| `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. |
|
|
|
|
<Callout type="warn">
|
|
The bot token controls your bot — keep it secret and only add **trusted** admin
|
|
chat IDs. Login alerts never include passwords.
|
|
</Callout>
|
|
|
|
<Callout type="info">
|
|
Email (SMTP) notifications mirror the same events (`smtpEnabledEvents`) if you'd
|
|
rather receive alerts by email — configure SMTP in Panel Settings.
|
|
</Callout>
|