Phase 38: Telegram Bridge - Context

Gathered: 2026-04-04 Status: Ready for planning Mode: Auto-generated (discuss skipped via workflow.skip_discuss)

## Phase Boundary

The user can message any Nexus agent from their phone via Telegram — text and voice notes both work, agent identity is visible on every reply, and the bot is set up through guided onboarding with no manual token entry in config files.

Requirements: TGRAM-01, TGRAM-02, TGRAM-03, TGRAM-04, TGRAM-05, TGRAM-06, ONBRD-03

## Implementation Decisions

Claude's Discretion

All implementation choices are at Claude's discretion — discuss phase was skipped per user setting. Use ROADMAP phase goal, success criteria, and codebase conventions to guide decisions.

Key research findings to incorporate:

grammy ^1.41.1 — TypeScript-native Telegram bot framework, long polling, clean file handling
Long polling via bot.start() — no public HTTPS required for Mac Mini behind NAT
Single bot for all agents — messages prefixed with [AgentName]
Telegram voice messages are OGG/Opus — download via ctx.getFile(), transcode to WAV 16kHz via ffmpeg before Whisper
TTS reply: synthesize via VoicePipelineService, convert WAV → OGG/Opus via ffmpeg, send via ctx.replyWithVoice()
Telegram token stored in nexus-settings.json (already in schema from Phase 36)
Bridge calls chatService and voicePipelineService directly (same-process, no HTTP round-trip)
Acknowledge updates immediately, process async to prevent Telegram resending
chatId → sessionId mapping: lightweight in-memory Map (single-user deployment)
Bridge service must be under 500 lines (TGRAM-06)
Onboarding BotFather setup: wizard step with guided token entry and validation

<code_context>

Existing Code Insights

Reusable Assets

server/src/services/voice-pipeline.ts — VoicePipelineService (transcribe, synthesize, formatForVoice)
server/src/services/chat.ts — chatService for conversation/message CRUD
server/src/services/nexus-settings.ts — telegramToken already in schema
server/src/routes/voice.ts — voice routes (pattern reference)

Established Patterns

Services as factory functions in server/src/services/
Routes in server/src/routes/
Onboarding wizard steps in ui/src/components/

Integration Points

server/src/app.ts — start telegram service conditionally when token present
server/src/services/nexus-settings.ts — read telegramToken
Onboarding wizard — add BotFather setup step

</code_context>

## Specific Ideas

No specific requirements — discuss phase skipped. Refer to ROADMAP phase description and success criteria.

## Deferred Ideas

None — discuss phase skipped.

2.8 KiB Raw Blame History