# Phase 38: Telegram Bridge - Context

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

<domain>
## 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

</domain>

<decisions>
## 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

</decisions>

<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>

<specifics>
## Specific Ideas

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

</specifics>

<deferred>
## Deferred Ideas

None — discuss phase skipped.

</deferred>
