Telegram bot

Operátor dostává dění kolem jobů do soukromého Telegram chatu a rovnou z něj rozhoduje. Bot je obousměrný: posílá notifikace a přijímá zpět schválení, rozhodnutí o nástrojích, volné instrukce agentovi i příkazy pro přehled stavu. Jde o interní nástroj, klienti s ním nepřijdou do styku.

Co bot posílá

Typy notifikací se zapínají konstantou TELEGRAM_NOTIFY v apps/api/src/telegram.ts (změna vyžaduje deploy).

Řízení z chatu

• Tlačítka pod zprávou provedou stejnou operaci jako admin UI (zápis do job_steering, probuzení kontejneru při schválení). Po použití se tlačítka odeberou; opakovaný stisk odpoví "Už vyřízeno".
• Reply na zprávu úkolu pošle text agentovi jako instrukci operátora (operator_message). Funguje i jako odpověď na volnou otázku agenta.
• /jobs vypíše aktivní úkoly (pending, approved, running) včetně označení těch, které čekají na vstup.
• /job <id> ukáže detail úkolu, posledních 10 událostí a kontextová tlačítka podle stavu (schválení, brána, pauza, opakování). Reply na detail také steeruje daný úkol.

Všechny akce z Telegramu se v auditní stopě (job_events) zapisují s by: "telegram".

Jak to drží pohromadě

• Odchozí zprávy odesílá výhradně API worker (care-api); bot token nikdy neopouští jeho secrets. Kontejner agenta posílá alerty přes POST /api/agent/alert jen jako text.
• Příchozí updates chodí na webhook POST /api/webhooks/telegram. Ověřuje se secret hlavička od Telegramu a jediný povolený chat_id; cokoli jiného se tiše zahodí.
• Mapování odeslaných zpráv na joby drží tabulka telegram_messages, díky ní funguje reply steering.
• Notifikace jsou best-effort: výpadek Telegramu nikdy neshodí job ani API, autoritativní záznam zůstává v job_events.

Nastavení

1. Vytvoř bota přes BotFather (/newbot) a ulož si token.
2. Napiš botovi první zprávu a z getUpdates zjisti chat.id.
3. Nastav secrety workeru care-api: TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID a TELEGRAM_WEBHOOK_SECRET (náhodný řetězec).
4. Zaregistruj webhook přes setWebhook s URL https://api.care.codebros.cz/api/webhooks/telegram, stejným secret_token a allowed_updates=["message","callback_query"].
5. Volitelně nastav nabídku příkazů přes setMyCommands (jobs, job).

Bez vyplněných secretů je celá integrace neaktivní: notifikace jsou no-op a webhook odmítá požadavky.