---
title: "Manage via Telegram"
description: "Platform-admin Telegram bot — whitelist RBAC, news approval, and Ring API executor from chat"
locale: "en"
---
# Manage via Telegram

> **Info**
> Use **Founder** / **Developer** tabs in the docs sidebar. This is the **admin bot** for operators — **not** member **Login via Telegram** (OIDC) or **Mini App initData** auth. Member auth: [Authentication](/docs/features/authentication.md). Stars membership: [SubscriptionConductor](/docs/features/subscriptions.md).

Ring ships a **Telegram Admin Bot** so platform admins can moderate news, run selected admin operations, and receive approval callbacks without opening the web admin UI — while still obeying the same RBAC SSOT as `/admin`.

| Concern | Truth |
|---------|--------|
| Webhook | `POST /api/telegram/admin-bot/webhook` |
| Code | `lib/telegram/admin-bot/` |
| RBAC | `features/auth/user-role.ts` — `isPlatformAdmin` / `isSuperadmin` |
| News approval | Bot callbacks + [News](/docs/features/news.md) / [News Kingdom](/docs/architecture/news-kingdom.md) |

### Do not confuse these Telegram surfaces

| Surface | Audience | Secret / crypto |
|---------|----------|-----------------|
| **Login via Telegram** | Members (browser) | `AUTH_TELEGRAM_ID` / `SECRET` — OIDC at `oauth.telegram.org` |
| **Mini App initData** | Members (WebApp client) | WebAppData HMAC — `TELEGRAM_MINI_APP_BOT_TOKEN` (fallbacks documented on Authentication) |
| **Link Telegram** (profile) | Logged-in members | Login Widget HMAC with `ADMIN_BOT_TOKEN` / `TELEGRAM_LOGIN_BOT_TOKEN` |
| **telegram_stars** membership | Paying members | Same Mini App bot token + Bot API `createInvoiceLink` — [SubscriptionConductor](/docs/features/subscriptions.md) |
| **Admin bot** (this page) | Platform admins | `ADMIN_BOT_TOKEN` + `ADMIN_BOT_WEBHOOK_SECRET` + whitelist |

### For founders

## Why operators use Telegram

Missile-hour ops and travel-friendly moderation: approve newsroom drafts, check critical queues, and keep an audit trail — without VPN into a desktop admin session.

### Trust & Brand fit

Telegram management sits with **authentication, security, and verification**:

- Only **whitelisted** Telegram IDs mapped to Ring `admin` / `superadmin` users can talk to the bot.
- Destructive actions (user delete, platform settings) stay **superadmin-only**.
- Admins must first **link Telegram** on their Ring profile (or sign in via Telegram OIDC so `communication.telegramId` is set) before the whitelist can see them.

  
- **[Security](/docs/features/security.md)** — Defense layers and admin posture.

  
- **[News](/docs/features/news.md)** — Telegram approval in the newsroom pipeline.

  
- **[Authentication](/docs/features/authentication.md)** — Member Login via Telegram OIDC + roles the bot must respect.

### Typical scenarios

- Autonomous newsroom draft arrives → admin taps Approve in Telegram → locale fan-out.
- On-call admin checks verification / order status via bot commands (platform-admin paths).
- Failed or unauthorized attempts are audit-logged.

### For developers

## Implementation

### Modules

| Path | Role |
|------|------|
| `app/api/telegram/admin-bot/webhook/route.ts` | Telegram updates ingress |
| `lib/telegram/admin-bot/bot-config.ts` | Token, webhook secret, `setWebhook` |
| `lib/telegram/admin-bot/whitelist.ts` | Map Telegram chat → Ring admin user via `communication.telegramId` |
| `lib/telegram/admin-bot/ring-api-executor.ts` | Operation-level RBAC before Ring HTTP |
| `lib/telegram/admin-bot/news-callback-handler.ts` | Inline news approve/reject |
| `lib/telegram/admin-bot/anthropic-router.ts` | Optional NL → tool routing |
| `lib/telegram/admin-bot/audit-logger.ts` | Interaction audit |
| `lib/telegram/admin-bot/TELEGRAM_BOT_RBAC.md` | RBAC policy SSOT (in-repo) |

### Env (verified names)

```bash
ADMIN_BOT_TOKEN=...
ADMIN_BOT_WEBHOOK_SECRET=...
```

Webhook URL shape: `https:///api/telegram/admin-bot/webhook` (HTTPS in production). Validate `secret_token` via `validateWebhookSecret`.

Member Login OIDC uses **different** env: `AUTH_TELEGRAM_ID` / `AUTH_TELEGRAM_SECRET` — see [Authentication](/docs/features/authentication.md).

### RBAC layers

1. **Whitelist** — sender Telegram ID must map to a Ring user in `PLATFORM_ADMIN_ROLES`.
2. **Executor** — per-operation checks in `ring-api-executor.ts`.
3. **Ring HTTP APIs** — session/MCP auth re-validates; bot must not bypass SSOT.

Strict **superadmin** examples: user delete, platform branding / AI settings mutations. Platform admins: news moderation, selected order/wallet/verification paths — see `TELEGRAM_BOT_RBAC.md`.

### Related member Telegram (not this bot)

| Path | Role |
|------|------|
| `features/auth/components/telegram-signin-button.tsx` | Login via Telegram OIDC |
| `lib/auth/telegram-oidc.ts` | Auth.js OIDC provider |
| `lib/auth/telegram-miniapp-initdata.ts` | Mini App WebAppData HMAC + bot token helper |
| `features/auth/components/telegram-linking-modal.tsx` | Legacy Login Widget linking |
| `app/api/auth/telegram/callback/route.ts` | Widget callback (session required) |
| `lib/auth/telegram-login-widget-hash.ts` | Shared widget HMAC |
| `lib/payments/subscription/providers/telegram-stars-subscription.ts` | Stars XTR invoices |

## Related documentation

  
- [features/authentication](/docs/features/authentication.md) — Prerequisite: member Login via Telegram OIDC + Mini App initData vs this admin bot.

  
- [features/subscriptions](/docs/features/subscriptions.md) — See-also: telegram_stars invoices share the Mini App bot token helper — not this admin webhook.

  
- [architecture/news-kingdom](/docs/architecture/news-kingdom.md) — Same-workflow: scoring, promotion, and Telegram approve callbacks.

  
- [development/generative-newsroom](/docs/development/generative-newsroom.md) — Next-step: draft → image → Telegram approve pipeline.

  
- [development/ring-mcp](/docs/development/ring-mcp.md) — See-also: IDE MCP twin for the same clone’s admin operations.

  
- [api/admin](/docs/api/admin.md) — Depends-on: web admin HTTP surfaces the bot mirrors carefully.