Consolidate Telegram integration

Author: alexeygrigorev

assistants/podcast/.env.example

@@ -1,4 +1,2 @@
-TELEGRAM_BOT_API_KEY=
-TELEGRAM_CHAT_ID=
 GROQ_API_KEY=
 HERU_ENGINE=codex

assistants/podcast/README.md

@@ -1,7 +1,7 @@
 # DataOps Assistant: Podcast Skill
 
-Podcast skill module for DataOps Assistant. It collects podcast prep material
-from Telegram and local inputs, then generates podcast guest documents.
+Podcast skill module for DataOps Assistant. It processes podcast prep material
+routed from the shared DataOps intake and generates podcast guest documents.
 
 This directory is the canonical in-repo implementation for the podcast skill:
 `assistants/podcast/`. The operator-facing assistant is DataOps Assistant;
@@ -10,10 +10,12 @@ workflow templates, and dry-run tests. The old root-level `podcast-assistant/`
 import name is retained here only as migration history; active development uses
 this module path.
 
-Telegram is a DataOps Assistant intake/progress channel. This module is copied
-from the Telegram Writing Assistant shape, but the agent execution boundary uses
-Heru instead of calling Claude directly. Set `HERU_ENGINE=codex` or
-`HERU_ENGINE=claude` to choose which coding agent processes the inbox.
+Telegram is a shared DataOps intake channel, not a bot owned by this module.
+The deployed backend owns the single Telegram webhook, bot credentials,
+allowlist, and command routing. `/podcast` requests are represented as podcast
+assistant jobs and are then processed by this module's Heru boundary. Set
+`HERU_ENGINE=codex` or `HERU_ENGINE=claude` to choose which coding agent
+processes a local assistant run.
 
 ## Setup
 
@@ -23,18 +25,18 @@ From the DataOps checkout:
 cd assistants/podcast
 uv sync
 cp .env.example .env
-uv run python main.py
 ```
 
-Required `.env` values:
+Optional local processing `.env` values:
 
 ```bash
-TELEGRAM_BOT_API_KEY=...
-TELEGRAM_CHAT_ID=...
 GROQ_API_KEY=...
 HERU_ENGINE=codex
 ```
 
+Do not configure or start a separate Telegram polling bot from this directory.
+Shared Telegram configuration belongs to the deployed backend integration.
+
 `HERU_ENGINE` can be `codex` or `claude`. The DataOps checkout expects the local
 Heru source at `../heru` relative to the repo root for live processing. Heru is
 not installed by default because unit CI must run from a clean checkout without
@@ -45,12 +47,11 @@ running `/process` or `process_request.py`:
 uv pip install -e ../../../heru
 ```
 
-## Commands
+## Shared Telegram route
 
-- `/start` - show bot help
-- `/status` - show inbox and document counts
-- `/process` - process with the default `HERU_ENGINE`
-- `/process codex` or `/process claude` - process with a specific Heru engine
+The shared DataOps bot exposes `/podcast <notes>` alongside other capabilities
+such as `/social` and general operations intake. The podcast module does not
+own `/start`, `/status`, polling, webhook registration, or Telegram secrets.
 
 ## Layout
 

assistants/podcast/main.py

@@ -17,11 +17,7 @@
 from telegram import MessageEntity, Update
 from telegram.constants import MessageEntityType
 from telegram.ext import (
-    Application,
-    CommandHandler,
     ContextTypes,
-    MessageHandler,
-    filters,
 )
 
 from heru_runner import DEFAULT_ENGINE
@@ -30,8 +26,10 @@
 
 load_dotenv()
 
-TELEGRAM_BOT_API_KEY = os.getenv("TELEGRAM_BOT_API_KEY")
-TELEGRAM_CHAT_ID = int(os.getenv("TELEGRAM_CHAT_ID", "0") or 0)
+# Kept only for compatibility with the imported handler unit tests. The
+# production Telegram allowlist and bot credentials live in the shared backend
+# webhook; this module no longer starts an independent polling bot.
+TELEGRAM_CHAT_ID = 0
 GROQ_API_KEY = os.getenv("GROQ_API_KEY")
 HERU_ENGINE = os.getenv("HERU_ENGINE", DEFAULT_ENGINE)
 HERU_MODEL = os.getenv("HERU_MODEL")
@@ -515,24 +513,10 @@ async def error_handler(update: Update, context: ContextTypes.DEFAULT_TYPE) -> N
 
 
 def main() -> None:
-    ensure_directories()
-    if not TELEGRAM_BOT_API_KEY:
-        raise RuntimeError("TELEGRAM_BOT_API_KEY is required")
-    if not TELEGRAM_CHAT_ID:
-        raise RuntimeError("TELEGRAM_CHAT_ID is required")
-
-    application = Application.builder().token(TELEGRAM_BOT_API_KEY).build()
-    application.add_handler(CommandHandler("start", start_command))
-    application.add_handler(CommandHandler("status", status_command))
-    application.add_handler(CommandHandler("process", process_command))
-    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_text_message))
-    application.add_handler(MessageHandler(filters.VOICE, handle_voice_message))
-    application.add_handler(MessageHandler(filters.AUDIO, handle_audio_message))
-    application.add_handler(MessageHandler(filters.PHOTO, handle_photo_message))
-    application.add_handler(MessageHandler(filters.VIDEO | filters.ANIMATION, handle_video_message))
-    application.add_handler(MessageHandler(filters.Document.ALL, handle_document_message))
-    application.add_error_handler(error_handler)
-    application.run_polling(allowed_updates=Update.ALL_TYPES)
+    raise RuntimeError(
+        "The podcast module no longer starts a Telegram bot. "
+        "Use the shared DataOps /api/webhook/telegram integration and /podcast route."
+    )
 
 
 if __name__ == "__main__":

backend/README.md

@@ -52,11 +52,38 @@ npm run seed
 From the repository root, `npm run seed:backend` runs both default user and
 template seeders.
 
-### Social draft assistant configuration
+### Shared Telegram and assistant configuration
 
-The first social drafting slice is covered by local tests with mocked external
-services. A real local route call uses configured z.ai and Typefully credentials
-when the target account is unambiguous:
+DataOps has one Telegram bot and one webhook:
+
+```text
+POST /api/webhook/telegram
+```
+
+The webhook routes ordinary messages and attachments to intake, `/podcast` to
+the podcast assistant job flow, and `/social` to social drafting. Assistant
+modules do not own separate Telegram tokens, polling processes, or webhooks.
+
+Local development can use `TELEGRAM_BOT_TOKEN`,
+`TELEGRAM_WEBHOOK_SECRET`, and comma-separated
+`TELEGRAM_ALLOWED_CHAT_IDS`. Production uses one out-of-band AWS Secrets
+Manager JSON secret named by `TELEGRAM_INTEGRATION_SECRET_NAME`:
+
+```json
+{
+  "botToken": "...",
+  "webhookSecret": "...",
+  "allowedChatIds": ["..."]
+}
+```
+
+Do not commit real values. The webhook fails closed when its configuration is
+missing, rejects a wrong Telegram secret header, and rejects chats outside the
+allowlist.
+
+The social drafting path is covered by local tests with mocked external
+services. A direct local route call can still exercise the assistant without
+Telegram:
 
 ```bash
 curl -X POST http://localhost:3000/api/assistant-social-drafts/mock-telegram \
@@ -75,8 +102,10 @@ Production-style external calls require managed credentials and account config:
 | `TYPEFULLY_API_KEY` | Typefully API key for saved draft creation |
 | `TYPEFULLY_SOCIAL_SET_ALEXEY` | Typefully social set id for Alexey / `Al_Grigor` |
 | `TYPEFULLY_SOCIAL_SET_DATATALKSCLUB` | Typefully social set id for DataTalksClub |
-| `TELEGRAM_WEBHOOK_SECRET` | Telegram webhook secret token for real webhook delivery |
-| `TELEGRAM_BOT_TOKEN` | Telegram bot token for optional replies |
+| `TELEGRAM_INTEGRATION_SECRET_NAME` | Production shared Telegram JSON secret name |
+| `TELEGRAM_WEBHOOK_SECRET` | Local-only webhook secret fallback |
+| `TELEGRAM_BOT_TOKEN` | Local-only bot token fallback for replies |
+| `TELEGRAM_ALLOWED_CHAT_IDS` | Local-only comma-separated chat allowlist fallback |
 
 The assistant route creates Typefully saved drafts only. It does not schedule or
 publish posts. Automated tests use mocked z.ai and Typefully clients; real z.ai,

backend/src/assistant/socialDraftAssistant.ts

@@ -383,15 +383,15 @@ async function runSocialDraftAssistant(
     requestedBy: actorId,
     inputRefs: [{
       type: 'source-message',
-      title: 'Mock Telegram social drafting request',
+      title: 'Telegram social drafting request',
       id: source.messageId,
-      metadata: {
+      metadata: Object.fromEntries(Object.entries({
         source: 'telegram',
         chatId: source.chatId,
         chatTitle: source.chatTitle,
         senderHandle: source.senderHandle,
         text: source.text,
-      },
+      }).filter(([, value]) => value !== undefined)),
     }],
     approvalRequired: true,
     approval: { status: 'pending' },

backend/src/router.ts

@@ -57,6 +57,7 @@ const AUTH_EXEMPT_PATHS = new Set([
 function isAuthExempt(method: string, path: string): boolean {
   if (AUTH_EXEMPT_PATHS.has(path)) return true;
   if (method === 'POST' && path === '/api/v1/intake/email-documents') return true;
+  if (method === 'POST' && path === '/api/webhook/telegram') return true;
   // Static assets
   if (method === 'GET' && path.startsWith('/public/')) return true;
   return false;