Telegram App Flow

This page explains how Telegram works with Nova.

User journey

1. User starts the bot.
2. User links account with the dashboard flow.
3. User sends natural-language requests in Telegram.
4. Telegram routes the instruction to TaskOrchestratorService.
5. Orchestrator updates task lifecycle/thread and invokes agent-v2 kernel execution.
6. For mutating actions, Nova asks for approval before execution.

Main endpoints

• POST /v1/telegram/app/webhook
• GET /v1/telegram/app/webhook/status (authenticated diagnostics)
• POST /v1/telegram/app/link/complete
• POST /v2/agent/runs (orchestrator-backed runtime execution target)
• POST /v2/agent/approvals/:approvalId/confirm (internal approval execution target)

Current experience

• command support exists (/start, /help, etc.)
• natural-language messages are primary
• reconnect guidance is shown in-chat when integrations are missing
• each instruction turn is reflected in task thread entries (user_input, runtime outcome, approvals)

Safety notes

• callback confirmations are ownership-checked
• callback confirmations are replay-protected
• callback paths are rate-limited
• Telegram webhook is auto-reconciled at API boot to TELEGRAM_APP_WEBHOOK_BASE_URL/<API_PREFIX>/telegram/app/webhook