# Telegram bot

> Optional remote control for admins and a self-serve view for users, without leaving Telegram.

Source: https://joinnasnet.com/en/guides/nasnet-linux/telegram-bot/
Last updated: 2026-08-14

---

## Overview

The Telegram bot is optional and off by default. Turned on, it gives admins a
remote control for the panel and gives users their subscription details without
a browser. It runs inside the same `nasnet-panel` process, and it fails safely:
if the bot cannot start, whether from a bad token or no network, the panel logs the error and
carries on serving the web panel and the API.

## Before you start

- A bot token from [@BotFather](https://t.me/BotFather).
- Your numeric Telegram user ID, which [@userinfobot](https://t.me/userinfobot)
  will tell you.
- Decide between polling and webhook. Polling needs no public URL and is the
  default; webhook needs a public HTTPS endpoint.

## Steps

1. Create the bot with @BotFather and copy its token.
2. Set the keys in `.env`:

   ```dotenv
   TELEGRAM_ENABLED=true
   TELEGRAM_BOT_TOKEN=123456:ABC-your-token
   ADMIN_IDS=11111111,22222222
   ```

3. Restart the panel. The IDs in `ADMIN_IDS` are synced as admins in the
   database on startup.
4. If the panel's network cannot reach the Telegram Bot API directly, route the
   bot's traffic through a SOCKS5 proxy:

   ```dotenv
   TELEGRAM_PROXY_ENABLED=true
   TELEGRAM_PROXY_TYPE=socks5
   TELEGRAM_PROXY_HOST=127.0.0.1
   TELEGRAM_PROXY_PORT=1080
   TELEGRAM_PROXY_USERNAME=
   TELEGRAM_PROXY_PASSWORD=
   ```

   These are also editable from **Settings → Telegram**, and the database value
   overrides `.env`.
5. Message the bot to confirm it answers.

## Reference

| Mode | Set | Notes |
| ---- | --- | ----- |
| Polling (default) | `BOT_MODE=polling` | The panel long-polls Telegram. No public URL or inbound port needed. |
| Webhook | `BOT_MODE=webhook` and `WEBHOOK_URL=https://your-domain/...` | Telegram pushes updates to your URL. Requires a public HTTPS endpoint. |

| Variable | What it does | Default |
| -------- | ------------ | ------- |
| `TELEGRAM_ENABLED` | Turns the bot on. | `false` |
| `TELEGRAM_BOT_TOKEN` | The @BotFather token. | unset |
| `ADMIN_IDS` | Comma-separated Telegram user IDs treated as admins. | unset |
| `BOT_MODE` | `polling` or `webhook`. | `polling` |
| `WEBHOOK_URL` | The endpoint Telegram pushes to in webhook mode. | empty |
| `TELEGRAM_PROXY_ENABLED` | Routes Bot API traffic through a SOCKS5 proxy. | `false` |

**What admins can do from the bot:** manage users and subscriptions, create
manual subscriptions, manage inbounds, outbounds and routing or balancing rules,
manage SNI values, toggle maintenance mode and broadcast messages, export data,
trigger backups, review the audit log, and view system status.

**What users can do:** view their subscription, covering the link, QR code, remaining data
and time, and devices.

The panel also supports link tokens that associate a panel account with a
Telegram identity, so the same person is recognised across the web panel, the
subscriber panel and the bot.

## Troubleshooting

**The bot never answers, but the panel is fine.** That is the designed failure
mode. Check the panel logs for the bot's startup error, which is usually an invalid token or an
unreachable Bot API are the two usual causes, and the second is what the SOCKS5
proxy settings exist for.

## Related

- [Settings](/en/guides/nasnet-linux/settings/)
- [Subscriber panel](/en/guides/nasnet-linux/subscriber-panel/)
- [Alerts](/en/guides/nasnet-linux/alerts/)