Telegram bot

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.
• Your numeric Telegram user ID, which @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:

   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:

   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
• Subscriber panel
• Alerts