--- title: "Керування через Telegram" description: "Telegram-бот адміністратора платформи — RBAC із білим списком, затвердження новин і виконавець Ring API з чату" locale: "uk" --- # Керування через Telegram > **Info** > Використовуйте вкладки **Founder** / **Developer** на бічній панелі документації. Це **бот адміністратора** для операторів — **не** **Login via Telegram** учасника (OIDC) і не автентифікація через `initData` Mini App. Автентифікація учасника: [Authentication](/docs/features/authentication.md). Членство Stars: [SubscriptionConductor](/docs/features/subscriptions.md). Ring постачає **Telegram Admin Bot**, щоб адміністратори платформи могли модерувати новини, виконувати вибрані адміністративні операції та отримувати callback-и затвердження без відкриття веб-інтерфейсу адміністратора — і водночас дотримуватися того самого RBAC SSOT, що й `/admin`. || Зона | Факт | ||---------|--------| || Webhook | `POST /api/telegram/admin-bot/webhook` | || Код | `lib/telegram/admin-bot/` | || RBAC | `features/auth/user-role.ts` — `isPlatformAdmin` / `isSuperadmin` | || Затвердження новин | Callback-и бота + [News](/docs/features/news.md) / [News Kingdom](/docs/architecture/news-kingdom.md) | ### Не плутайте ці поверхні Telegram || Поверхня | Аудиторія | Секрет / криптографія | ||---------|----------|-----------------| || **Login via Telegram** | Учасники (браузер) | `AUTH_TELEGRAM_ID` / `SECRET` — OIDC на `oauth.telegram.org` | || **Mini App initData** | Учасники (клієнт WebApp) | HMAC WebAppData — `TELEGRAM_MINI_APP_BOT_TOKEN` (fallback-и описані в Authentication) | || **Link Telegram** (профіль) | Учасники, які ввійшли | HMAC Login Widget з `ADMIN_BOT_TOKEN` / `TELEGRAM_LOGIN_BOT_TOKEN` | || Членство `telegram_stars` | Учасники, які платять | Той самий токен Mini App бота + Bot API `createInvoiceLink` — [SubscriptionConductor](/docs/features/subscriptions.md) | || **Admin bot** (ця сторінка) | Адміністратори платформи | `ADMIN_BOT_TOKEN` + `ADMIN_BOT_WEBHOOK_SECRET` + білий список | ### For founders ## Навіщо операторам Telegram Операції під час термінових годин і модерація в дорозі: затверджуйте чернетки редакції, перевіряйте критичні черги та зберігайте аудиторський слід — без VPN до настільної сесії адміністратора. ### Відповідність довірі та бренду Керування через **authentication, security і verification**: - Розмовляти з ботом можуть лише **додані до білого списку** ідентифікатори Telegram, зіставлені з користувачами Ring `admin` / `superadmin`. - Деструктивні дії (видалення користувача, налаштування платформи) залишаються доступними лише **superadmin**. - Адміністратори спочатку мають **підключити Telegram** у профілі Ring (або увійти через Telegram OIDC, щоб було встановлено `communication.telegramId`), перш ніж білий список зможе їх побачити. - **[Безпека](/docs/features/security.md)** — Рівні захисту та адміністративна позиція. - **[Новини](/docs/features/news.md)** — Затвердження через Telegram у редакційному конвеєрі. - **[Автентифікація](/docs/features/authentication.md)** — OIDC учасника Login via Telegram + ролі, яких має дотримуватися бот. ### Типові сценарії - Надходить чернетка автономної редакції → адміністратор натискає Approve у Telegram → розподіл за локалями. - Адміністратор on-call перевіряє статус верифікації / замовлення через команди бота (шляхи адміністратора платформи). - Невдалі або неавторизовані спроби записуються до аудиту. ### For developers ## Реалізація ### Модулі || Шлях | Роль | ||------|------| || `app/api/telegram/admin-bot/webhook/route.ts` | Вхід для оновлень Telegram | || `lib/telegram/admin-bot/bot-config.ts` | Токен, секрет webhook, `setWebhook` | || `lib/telegram/admin-bot/whitelist.ts` | Відображення чату Telegram → користувач адміністратора Ring через `communication.telegramId` | || `lib/telegram/admin-bot/ring-api-executor.ts` | RBAC на рівні операції перед Ring HTTP | || `lib/telegram/admin-bot/news-callback-handler.ts` | Inline approve/reject новин | || `lib/telegram/admin-bot/anthropic-router.ts` | Необов’язкова маршрутизація NL → tool | || `lib/telegram/admin-bot/audit-logger.ts` | Аудит взаємодій | || `lib/telegram/admin-bot/TELEGRAM_BOT_RBAC.md` | SSOT політики RBAC (у репозиторії) | ### Env (перевірені назви) ```bash ADMIN_BOT_TOKEN=... ADMIN_BOT_WEBHOOK_SECRET=... ``` Форма URL webhook: `https:///api/telegram/admin-bot/webhook` (у production — HTTPS). Перевіряйте `secret_token` через `validateWebhookSecret`. OIDC учасника Login використовує **інші** env: `AUTH_TELEGRAM_ID` / `AUTH_TELEGRAM_SECRET` — див. [Authentication](/docs/features/authentication.md). ### Рівні RBAC 1. **Білий список** — Telegram ID відправника має бути зіставлений із користувачем Ring у `PLATFORM_ADMIN_ROLES`. 2. **Виконавець** — перевірки для кожної операції в `ring-api-executor.ts`. 3. **HTTP API Ring** — автентифікація сесії/MCP перевіряє повторно; бот не повинен обходити SSOT. Приклади, суворо доступні **superadmin**: видалення користувача, зміни бренду платформи / налаштувань AI. Адміністратори платформи: модерація новин, вибрані шляхи замовлень/гаманця/верифікації — див. `TELEGRAM_BOT_RBAC.md`. ### Пов’язаний Telegram учасника (не цей бот) || Шлях | Роль | ||------|------| || `features/auth/components/telegram-signin-button.tsx` | Login via Telegram OIDC | || `lib/auth/telegram-oidc.ts` | Провайдер OIDC для Auth.js | || `lib/auth/telegram-miniapp-initdata.ts` | HMAC WebAppData Mini App + хелпер токена бота | || `features/auth/components/telegram-linking-modal.tsx` | Застаріле підключення Login Widget | || `app/api/auth/telegram/callback/route.ts` | Callback віджета (потрібна сесія) | || `lib/auth/telegram-login-widget-hash.ts` | Спільний HMAC віджета | || `lib/payments/subscription/providers/telegram-stars-subscription.ts` | Рахунки Stars XTR | ## Пов’язана документація - [features/authentication](/docs/features/authentication.md) — Передумова: Login via Telegram OIDC учасника + initData Mini App у порівнянні з цим ботом адміністратора. - [features/subscriptions](/docs/features/subscriptions.md) — Див. також: рахунки telegram_stars використовують спільний хелпер токена Mini App — не цей webhook адміністратора. - [architecture/news-kingdom](/docs/architecture/news-kingdom.md) — Той самий процес: оцінювання, просування та callback-и затвердження в Telegram. - [development/generative-newsroom](/docs/development/generative-newsroom.md) — Наступний крок: конвеєр чернетка → зображення → затвердження в Telegram. - [development/ring-mcp](/docs/development/ring-mcp.md) — Див. також: IDE MCP-двійник для адміністративних операцій того самого клону. - [api/admin](/docs/api/admin.md) — Залежність: HTTP-поверхні вебадміністратора, які бот обережно віддзеркалює.