---
title: Task 5.3 Telegram Bot Command and Notification Foundation
tags: [taskmaster, telegram, bot, notifications]
created: 2026-05-24
status: 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.