---
title: Telegram-бот
description: Подключите Telegram-бота к 3x-ui для выполнения команд, периодических отчётов, оповещений о событиях (вход, CPU, доступность узлов), резервных копий и самообслуживания клиентов.
icon: Send
---

3x-ui умеет управлять Telegram-ботом для мониторинга, оповещений, резервного
копирования и удалённого управления. Администраторы получают полный контроль;
обычные пользователи (привязанные по Telegram ID) могут проверять собственный
расход трафика и ссылки.

<Callout type="info">
  Ищете новости и поддержку сообщества? Присоединяйтесь к официальному
  Telegram-каналу [@XrayUI](https://t.me/XrayUI). Это отдельный канал, не
  связанный с описанным ниже ботом, которого вы запускаете самостоятельно для
  управления собственной панелью.
</Callout>

## Настройка

<Steps>

<Step>
### Создайте бота

Напишите [@BotFather](https://t.me/BotFather), отправьте `/newbot` и скопируйте
**токен бота**.
</Step>

<Step>
### Узнайте свой Telegram ID

Получите свой числовой идентификатор пользователя Telegram (после подключения
бот сообщит его по собственной команде `/id`). Это ваш **админский** ID.
</Step>

<Step>
### Настройте панель

В настройках панели включите Telegram-бота и задайте **токен** и **админские
chat ID** (через запятую). Сохраните, затем напишите своему боту.
</Step>

</Steps>

Проверьте свой токен, админские ID и расписание отчётов, прежде чем вставлять их
в панель:

<TelegramSetupHelper />

## Команды

Эти команды отображаются в меню команд Telegram: `/start`, `/help`, `/status`, `/id`.
Дополнительные команды:

| Команда            | Кому   | Действие                                                     |
| ------------------ | ------ | ------------------------------------------------------------ |
| `/start`           | всем   | Приветствие и меню встроенных кнопок; непривязанный аккаунт получает только свой Telegram ID |
| `/help`            | обоим  | Меню встроенных кнопок                                       |
| `/status`          | обоим  | Подтверждает, что бот работает                               |
| `/id`              | всем   | Показывает ваш числовой Telegram ID                          |
| `/usage <arg>`     | обоим  | Администраторы ищут клиентов; пользователи смотрят свой расход |
| `/inbound <remark>`| админ  | Показывает сведения о входящем подключении                   |
| `/restart`         | админ  | Перезапускает Xray                                          |

Пользователь — это аккаунт Telegram, привязанный хотя бы к одному клиенту. Любой
другой аккаунт может выполнять только `/start` и `/id`; остальные его команды и
нажатия кнопок бот игнорирует. Чтобы привязать клиента, нажмите
**Ссылка-приглашение** в карточке клиента в боте и отправьте ему ссылку `t.me`: первый
открывший её аккаунт привязывается ко всем клиентам с этим ID подписки. ID
подписки служит кодом приглашения, поэтому делайте его длинным и случайным.
У каждого аккаунта пять попыток в час, после чего администраторы получают
уведомление.

Администраторам также доступны сценарии со встроенными кнопками: использование
сервера, отсортированные отчёты по трафику, сброс трафика, резервные копии БД,
журналы блокировок, список входящих подключений/клиентов, онлайн-клиенты,
«скоро исчерпают» и полноценный мастер **добавления клиента**. Обычным
пользователям доступны кнопки для своего расхода, ссылок на подписку, отдельных
ссылок и QR-кодов.

## Отчёты и оповещения

- **Периодический отчёт** — по расписанию `tgRunTime` (по умолчанию `@daily`) бот
  отправляет администраторам сведения об использовании сервера (хост, версии,
  время работы, нагрузка, память, онлайн-клиенты, трафик), список
  исчерпанных/истекающих клиентов и — если включён `tgBotBackup` — резервную
  копию базы данных и конфигурации Xray. Клиенты, привязанные по Telegram ID,
  получают собственные предупреждения об истечении срока/исчерпании квоты.
- **Оповещения о событиях** — выбираются параметром `tgEnabledEvents` (по умолчанию `login.attempt,cpu.high`):

  | Событие         | Когда                                                   |
  | --------------- | ------------------------------------------------------- |
  | `login.attempt` | Вход в панель удался или не удался (с IP и именем пользователя) |
  | `cpu.high`      | Загрузка CPU превышает `tgCpu` процентов (по умолчанию 80) |
  | `memory.high`   | Использование памяти превышает `tgMemory` процентов (по умолчанию 80) |
  | `xray.crash`    | Аварийное завершение Xray-core                          |
  | `outbound.down` / `outbound.up` | Исходящее подключение упало / восстановилось |
  | `node.down` / `node.up`         | Узел ушёл в офлайн / вернулся в строй    |

Время предупреждения определяется параметрами `expireDiff` (дней до истечения
срока) и `trafficDiff` (ГБ оставшейся квоты); оба по умолчанию равны `0`
(отключено).

## Параметры

| Параметр       | По умолчанию               | Значение                                       |
| -------------- | -------------------------- | ---------------------------------------------- |
| `tgBotEnable`  | `false`                    | Главный переключатель вкл./выкл.               |
| `tgBotToken`   | _(секрет)_                 | Токен Bot API.                                 |
| `tgBotChatId`  | _(нет)_                    | **Админские** Telegram ID через запятую.       |
| `tgBotProxy`   | _(нет)_                    | Прокси `socks5://`, `http://` или `https://`.  |
| `tgBotAPIServer` | _(по умолчанию)_         | Пользовательский сервер Telegram Bot API.      |
| `tgRunTime`    | `@daily`                   | Расписание отчётов (cron / `@daily` / `@every …`).|
| `tgBotBackup`  | `false`                    | Прикладывать резервную копию БД к периодическому отчёту. |
| `tgCpu` / `tgMemory` | `80` / `80`          | Пороги оповещений по CPU / памяти (в процентах). |
| `tgLang`       | `en-US`                    | Язык бота.                                      |
| `tgEnabledEvents` | `login.attempt,cpu.high`| Какие события доставлять.                       |

<Callout type="warn">
  Токен бота управляет вашим ботом — храните его в секрете и добавляйте только
  **доверенные** админские chat ID. Оповещения о входе никогда не содержат
  паролей.
</Callout>

<Callout type="info">
  Уведомления по электронной почте (SMTP) дублируют те же события
  (`smtpEnabledEvents`), если вы предпочитаете получать оповещения на почту —
  настройте SMTP в настройках панели.
</Callout>