nick-doc/09 - Audits/Task 5.3 Telegram Bot Command and Notification Foundation.md

title, tags, created, status

title	tags	created	status
Task 5.3 Telegram Bot Command and Notification Foundation	taskmaster telegram bot notifications	2026-05-24	partial-foundation

Task 5.3 Telegram Bot Command and Notification Foundation

This document captures the first backend bot foundation pass.

Implemented foundation

• /api/telegram/status reports feature and webhook readiness without leaking bot or webhook secrets.
• /api/telegram/webhook is mounted only when Telegram features are enabled.
• Webhook requests require x-telegram-bot-api-secret-token to match TELEGRAM_WEBHOOK_SECRET_TOKEN.
• Webhook update handling dedupes by update_id or callback ID.
• Webhook handler classifies updates as:
  • command
  • callback
  • noop
  • duplicate

Configuration

Variable	Purpose
TELEGRAM_WEBHOOK_ENABLED	Enables webhook route
TELEGRAM_WEBHOOK_SECRET_TOKEN	Telegram webhook secret token
TELEGRAM_WEBHOOK_REPLAY_WINDOW_MS	Duplicate update replay window

Tests

• Service-level tests cover command/callback/noop classification and duplicate handling.
• Route-level tests cover secret-token rejection and accepted command webhook processing.

Remaining work

• Implement actual command actions for /start, /help, /link, /status, /request, /offer, /payment, /dispute, and /settings.
• Add signed opaque callback payload issuance and resolution.
• Add outbound notification delivery, blocked-bot detection, retry metrics, and notification preferences.
• Persist webhook dedupe keys in shared storage instead of process memory.