(CODUX-225) Complete the Telegram connector

[numnx]

🧩 Task: Complete the Telegram connector

Automated task PR opened by Code UX for T04.

📋 Summary

Sprint: Sprint 225 · Chat connector completeness and verification · Task: T04

Complete and verify all six chat connectors through provider-specific profiles, correct authentication and session behavior, encrypted durable state, atomic routing and retries, REST/MCP/dashboard management, official-documentation evidence, deterministic contract coverage, and credential-gated checks limited to provider-controlled endpoints, with Discord prioritized.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.6-sol

⏱️ Timing

Started	2026-07-13 22:51:04 UTC
Finished	2026-07-13 23:06:56 UTC
Duration	15m 52s

📊 Token Usage

Metric	Value
Input tokens	205,779
Cached input tokens	7,390,976
Output tokens	34,375
Total tokens	7,631,130
Invocations	1
Tool calls	42
Active time	14m 44s

Included usage estimate (subscription/local login): $5.76

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Complete the Telegram profile using the documented Bot API webhook and message contracts while preserving managed and custom webhook bridges.

## Scope
- `src/domain/chat-connectors/providers/telegram.ts`
- Create `tests/backend/domain/chat-connectors/telegram.test.ts`
- `docs/settings/chat-connectors/telegram.md`
- `docs-web/architecture/chat-connectors/telegram.md`
- Official reference: [Telegram Bot API](https://core.telegram.org/bots/api)

## Implementation Requirements
1. Add an `official_api` schema with optional bot username and a write-only bot token plus webhook secret token; retain current managed and generic webhook schemas.
2. Authenticate official webhook ingress with exact constant-time comparison of `X-Telegram-Bot-Api-Secret-Token` and do not require synthetic HMAC or timestamp headers that Telegram does not send.
3. Normalize `message`, `channel_post`, and supported edited-message forms, use `update_id` plus message identity for duplicate control, retain topic/thread IDs, and ignore bot-originated updates that would create reply loops.
4. Send replies through the fixed `https://api.telegram.org/bot<token>/sendMessage` origin using chat and topic IDs, safe text limits, and reply parameters; parse Bot API `ok`, `result`, `error_code`, `description`, and `parameters.retry_after` fields.
5. Verify tokens with `getMe` and expose `getWebhookInfo` diagnostics without mutating webhook configuration during a verification action.
6. Cover correct and incorrect secret headers, update variants, numeric IDs beyond 32-bit ranges, topic routing, API-level errors returned with HTTP 200, 429 backoff, timeouts, loop suppression, and legacy bridges using deterministic mocks.

## Constraints
- Never log or persist a URL containing the Telegram bot token.
- Official mode must use Telegram's provider-controlled API origin; custom endpoints remain available only through explicit legacy bridge modes.
- Treat ambiguous send failures conservatively to avoid duplicate external messages.
- Do not modify other provider modules or shared generated docs-web artifacts.

## Verification
- Run `pnpm run test:backend -- tests/backend/domain/chat-connectors/telegram.test.ts`.
- Run `pnpm run lint`.
- Confirm an invalid Bot API envelope fails even when its HTTP response is 200 and a 429 schedules the documented retry delay.

🌿 Branch Info

Base: feature/CODUX-225-chat-connector-completeness-and-verification
Head: task/feature-codux-22-t04-codex-8cd239e4-mrjtggh8

---

🤖 Generated by Code UX