3x-ui/docs/content/docs/en/operations/telegram-bot.mdx

---
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.
</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.        |
| `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>