Admin Panel (Mini App)

Enable and operate Alita Robot's optional Telegram Mini App dashboard — environment variables, HTTPS, reverse proxy, entry points and failure modes.

The admin panel is an optional Telegram Mini App dashboard served by the bot’s own HTTP server under /panel. It is off by default: with PANEL_ENABLED unset or false, /panel and /panel/api/v1/* return 404 and the bot behaves exactly as before — no dashboard buttons, no menu button change, nothing new to secure.

There is no second process, database or frontend build to deploy: the panel lives in the same binary and is served on the same port as /health, /metrics and /webhook.

Enable it

1. Pick the public HTTPS host the bot will answer on — the same host as WEBHOOK_DOMAIN is the usual choice.
2. Point a reverse proxy at the bot’s HTTP_PORT (default 8080) and forward /panel and /panel/api/*, plus /webhook if you use webhooks.
3. Set the variables below and restart the bot.
4. Send /start panel_<chat_id> to the bot in a private chat to check it.

No BotFather setup is needed: web_app buttons and the menu button open any HTTPS URL. BotFather’s /setdomain is for the Telegram Login Widget, which the panel does not use.

PANEL_ENABLED=true
PANEL_PUBLIC_URL=https://bot.example.com/panel

The bot serves the panel under /panel on its own port, and the shell calls /panel/api/v1/* with root-relative URLs. PANEL_PUBLIC_URL is the URL Telegram opens, so it must end with /panel unless your proxy rewrites the host root to the panel.

With the repository’s docker-compose.yml, only the variables listed under services.alita.environment reach the container: add PANEL_ENABLED and PANEL_PUBLIC_URL there (the same goes for any other optional variable).

Environment variables

PANEL_PUBLIC_URL must be https://; http:// is accepted only when DEBUG=true, because Telegram refuses to open a Mini App from an insecure origin.

HTTPS and the reverse proxy

Telegram only opens Mini Apps from an HTTPS origin. The bot itself speaks plain HTTP on HTTP_PORT, so the certificate belongs to whatever sits in front of it — Caddy, nginx, Traefik, Cloudflare Tunnel, or your platform’s load balancer.

With Caddy in front of the same container:

bot.example.com {
	reverse_proxy 127.0.0.1:8080
}

With nginx:

server {
	listen 443 ssl;
	server_name bot.example.com;
	# ssl_certificate / ssl_certificate_key ...

	location /panel {
		proxy_pass http://127.0.0.1:8080;
		proxy_set_header Host $host;
		proxy_set_header X-Forwarded-Proto $scheme;
	}

	location /webhook {
		proxy_pass http://127.0.0.1:8080;
	}
}

PANEL_PUBLIC_URL is what the buttons open, so it must be the proxied panel URL (for example https://bot.example.com/panel), not http://localhost:8080. Both proxy snippets above pass the path through unchanged, which is what the panel expects. If the proxy serves the panel on a different host than the webhook, that is fine — both are just paths on the one server.

Optional: the direct Mini App link

By default a group button opens the bot’s private chat with a /start panel_<chat_id> deep link; the bot then replies with a web_app button that launches the panel. That works with no BotFather setup. Creating a Mini App in BotFather gives you a short name, so the button can skip the hop:

1. In @BotFather, send /newapp, pick the bot and follow the prompts — or use /mybots → your bot → Bot Settings → Configure Mini App → Enable Mini App.
2. Give it a title and the panel URL: the same value as PANEL_PUBLIC_URL.
3. Note the short name BotFather shows for the Mini App.
4. Set PANEL_MINIAPP_SHORTNAME to that short name and restart.

Group buttons then point straight at https://t.me/<bot>/<short_name>?startapp=chat_<chat_id>, which opens the panel without a message in between. If the short name is wrong or the Mini App is not enabled in BotFather, Telegram opens an empty page — remove the variable to fall back to the deep link.

Entry points

With the panel enabled the bot adds these, and nothing else changes:

With the panel disabled both group keyboards are exactly what they were before: one button each, no dashboard row, and the menu button is never touched.

What admins see

The panel authenticates every request with Telegram initData; there are no passwords, cookies or server-side sessions to manage, and the signature is checked against the bot token on arrival.

• The chat list shows the groups where the bot has seen you, ordered by last activity and capped at 50. When the panel is opened from a group’s button or Mini App link, it opens that chat directly. The session itself makes no Telegram calls: opening a chat is what verifies your role there.
• Opening a chat shows its details: your role (Admin or Read-only) and whether the bot is an admin there, followed by the dashboard screens registered for that chat.
• The overview screen is the first entry in the dashboard list: the Telegram member count, a 7, 30 or 90 day chart of messages, joins and leaves, the window’s moderation count and the five most recent moderation actions (action, actor, target and time — never message text). Switching the window redraws without a page reload, and a chat with no recorded activity says so instead of drawing an empty chart.
• Only members of a group can open it. Non-admin members see the chat read-only; anyone else is refused (403 not_member), and private chats and channels are not served. When the bot is not an admin in the chat, values are still shown but every change is refused, because the bot could not carry it out.
• A user with no groups sees an empty state explaining how to add the bot or how to /connect a group.

Failure modes

Manual smoke checklist

Run this once after enabling the panel on a deployment (the Telegram items need a real client and cannot run in CI):

1. Open PANEL_PUBLIC_URL in a browser outside Telegram: the shell renders and reports the missing initData instead of crashing.
2. Open it from a group’s dashboard button inside Telegram: that chat opens directly, and ← All chats leads to the chat list.
3. Switch the Telegram theme between light and dark while the panel is open: backgrounds and text follow the --tg-theme-* colours.
4. Open it for a user with no groups: the empty state explains how to add the bot, with no browser console error.
5. Throttle the network to slow 3G and reload: the loading state appears first, then the list, with no layout shift or blank screen.
6. Open it for a user with many groups (the list is capped at 50): the list scrolls smoothly and every title is selectable.
7. Open the same URL inside web.telegram.org: the Mini App loads in the iframe with no frame-ancestors violation in the console, and the same URL also works standalone in the mobile Telegram app.
8. In a group, /settings shows two buttons and the panel button opens the panel for that group; with PANEL_ENABLED=false the second row is gone.
9. Open Warnings: a warning older than the chat’s warn expiry is labelled expired, and Remove newest warning deletes one entry. Open Timeline with more than 50 events and scroll: the next page appends without the list jumping, and the action/actor filters return only matching rows.