# Telegram Handbook

Telegram in Oshun is a channel family, not one bot screen. It includes the
member-facing Lilith bot, private/group command surfaces, webhook and long-poll
composition, grounded answers, rooms and reminders, voice notes and speech,
inline keyboards and callbacks, deep links, a Telegram Mini App, web account
linking and Login Widget verification, editorial channels, inline mode,
payments/upgrade, delivery limits, admin registry, deployment, observability,
and safety/privacy controls.

This handbook maps all of those capabilities and keeps **implemented**,
**wired**, **deployed**, and **planned** status distinct.

## Coverage map

| Aspect                | Start here                                                                                              | What it covers                                                                                                                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bot experience        | [Bot, commands, and conversation](./bot-commands-and-conversation.md)                                   | Update kinds, private/group scope, every registered and supported command family, callbacks, keyboards, deep links, presence, limits, and delivery.                                                 |
| Mini App and identity | [Mini App, authentication, and account linking](./mini-app-auth-and-account-linking.md)                 | Curated surfaces, Telegram WebApp bridge/theme, initData, scoped sessions, Login Widget, profile binding/unbinding, CORS, and primary-credential challenges.                                        |
| Member continuity     | [Rooms, reminders, notifications, and voice](./rooms-reminders-notifications-and-voice.md)              | Tara/Arete/Nyx/Nisaba/library rooms, continue/streak/settings, time zones, quiet hours, reminder lifecycle, scheduled delivery, stop/resume, STT, and TTS.                                          |
| Extended surfaces     | [Channels, inline, media, payments, and deep links](./channels-inline-media-payments-and-deep-links.md) | Editorial publishing/takedown, inline share/grounding, text/media/file delivery, deep-link routing, Mini App buttons, invoices, pre-checkout, receipts/refunds, and upgrades.                       |
| Trust                 | [Safety, privacy, grounding, and rights](./safety-privacy-grounding-and-rights.md)                      | Tier/channel boundaries, consent, crisis, grounding/abstention, audit/provenance, chat privacy, durable-memory gate, rate/abuse controls, retention, and deletion.                                  |
| Architecture          | [Architecture, data, contracts, and integrations](./architecture-data-contracts-and-integrations.md)    | Registry/dispatcher/boundary, BFF composition, Telegram library, bot and Mini App apps, stores/adapters, Sophia/rooms/reminders/payments, admin, web, and deployment boundaries.                    |
| Operations            | [Operations, observability, testing, and release](./operations-observability-testing-and-release.md)    | Configuration/secrets, webhook registration, command discoverability, update dedupe/claiming, send cycle, delivery receipts, blocked users, scheduled cycle, health, tests, release, and incidents. |

## Surface map

```mermaid
flowchart LR
  T[Telegram user/client] --> W[Bot webhook in Oshun BFF]
  T --> M[Telegram Mini App]
  T --> L[Login / account link]
  W --> C[Channel policy + bot handler]
  C --> S[Sophia grounding]
  C --> R[Rooms, reminders, preferences]
  C --> P[Upgrade / payments]
  C --> D[Bot API delivery]
  M --> A[Verified initData session]
  A --> B[Scoped BFF APIs]
  O[Operator/editorial flow] --> H[Telegram channels]
  I[Inline query] --> Q[Inline cards]
```

The live inbound bot path is the BFF webhook. The standalone
`apps/oshun/telegram-bot` package is retained as a long-poll/thin-client option
and is explicitly not a deployed service. The Mini App is a separate Next.js
surface. Web profile linking and admin channel registry are separate web/admin
flows.

## Channel identities

The V1 registry defines three Telegram channel ids:

| Channel id         | Intended use                                                                                         | Key boundary                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `telegram-bot`     | Private/group conversation, rooms, grounded answers, reminders, voice, identity, and Mini App entry. | Verified opt-in; crisis-capable; member/curated tiers only; personal commands private-only. |
| `telegram-miniapp` | Embedded curated workspace surfaces under Telegram's WebApp runtime.                                 | Verified initData and scoped short-lived session before protected BFF use.                  |
| `telegram-channel` | Operator/editorial broadcast publishing and takedown.                                                | Not crisis-capable; public broadcast is never a personal support channel.                   |

Cross-channel policy, capabilities, consent, residency, retention, disclosure,
and intent routing are described in
[Channel architecture](../../architecture/messaging-channels.md). The
Telegram-specific canonical technical narrative is
[Telegram Surfaces](../../features/telegram-surfaces.md).

## Status model

- **Contract/planner** — a pure function or typed port can validate and plan a
  provider action; it does not prove provider I/O.
- **Implemented** — real behavior exists and has direct tests.
- **Wired** — the supported BFF/web/Mini App/admin entry point composes it.
- **Deployed** — configuration, secret, route/task, and provider registration
  exist in the target environment.
- **End-to-end evidenced** — a current automated or controlled live check proves
  Telegram accepted and the user received/observed the result.
- **Fail-closed gap** — absent credentials, provider, store, or live transport
  returns an explicit unavailable/refusal state rather than fabricated success.

Do not infer delivery from a `BotResponse`, an invoice plan, a status-only Mini
App button, or a passing pure-handler test. Follow the effect to the Telegram
Bot API and its response/receipt.

## Functional inventory

### Conversation and discovery

- Bot command registration for private chats and a reduced group-chat scope.
- Menu button that opens the Mini App when configured or commands otherwise.
- `/start` payload deep links, bot-addressed commands, stale/unknown fallbacks,
  `/help`, and contextual inline keyboards.
- Private-chat protection for personal state and writes.
- Chat actions such as typing/recording/uploading presence.
- Telegram message, callback, inline-result, and callback-data limits.

### Member rooms and actions

- Tara ritual (`/sit`, legacy `/today`), Arete check-in, Nyx tonight window,
  Nisaba passage, library, continue point, streak, settings, and grounded Sophia
  questions (`/ask`).
- Save notes/links, reminder creation and delivery actions, time-zone capture,
  quiet hours, delivery stop/resume, voice preference, unlink, and upgrade.
- Honest unavailable behavior when a room or effect port is not connected.

### Media and embedded experience

- Text splitting and delivery, inline keyboards, documents/photos/voice where a
  response declares media, provider upload/download handling, and failure
  reporting.
- Voice-note STT with an explicit unconfigured state; optional TTS with length
  limits and upload presence.
- Seven curated Mini App surfaces—today, Sophia, Veritas, Nyx, Arete, Nisaba,
  and illustration—with theme/bridge and BFF integration boundaries.

### Publishing, inline, identity, and commerce

- Editorial Telegram-channel post synthesis, scheduling model, and takedown.
- Inline share/Sophia result builders with abuse/attribution controls.
- Login Widget verification, Mini App initData verification, scoped sessions,
  account linking/unlinking, and sensitive-action challenges.
- Upgrade routing and Telegram invoice, pre-checkout, successful-payment,
  receipt, and refund state models; actual rail depends on configured payment
  composition.

## User-facing identity

Telegram is a member/customer surface, so the presented assistant identity is
**Lilith**, not Eve. Eve may help operators build or administer the system, but
member chat, Mini App, voice, grounding disclosures, and crisis behavior use the
Lilith persona/policy boundary. See the
[Lilith member experience](../../../V3/docs/lilith/member-persona-and-experience.md).

## Reading paths

**Product/support:** read
[bot and commands](./bot-commands-and-conversation.md),
[rooms/reminders/voice](./rooms-reminders-notifications-and-voice.md), and
[Mini App and linking](./mini-app-auth-and-account-linking.md).

**Engineering:** read
[architecture](./architecture-data-contracts-and-integrations.md),
[trust](./safety-privacy-grounding-and-rights.md), and
[operations](./operations-observability-testing-and-release.md).

**QA/release:** use the same three engineering topics plus the
[Telegram walkthrough](../../../TELEGRAM_WALKTHROUGH/README.md) and the
[assistant-delivery journey](../../../WALKTHROUGH/journeys/telegram-bot-assistant-delivery.md).

## Canonical sources

- [Telegram Surfaces](../../features/telegram-surfaces.md) — V1 product and
  implementation narrative.
- [Telegram buildout/audit plan](../../TELEGRAM_SURFACE_PLAN_2026-08-05.md) —
  chronological defects, fixes, deployment findings, and remaining facts.
- [Telegram Mini App walkthrough](../../../TELEGRAM_WALKTHROUGH/README.md) —
  route/view interaction and gap inventory.
- `libs/oshun/messaging-channels/src/telegram` — channel contracts and pure
  behavior.
- `apps/oshun/bff/src/telegram` and `apps/oshun/bff/src/routes/telegram.ts` —
  live webhook composition, adapters, stores, and security state.
- `apps/oshun/telegram-miniapp`, `apps/oshun/telegram-bot`,
  `apps/oshun/web/src/app/profile/telegram`, and
  `apps/oshun/admin/src/app/messaging/telegram-channels` — app surfaces.

## Keeping this handbook true

When a command, update kind, callback, room, Mini App slug/action, Bot API call,
channel capability, binding/session scope, payment state, scheduled task,
deployment setting, or safety boundary changes, update the owning deep dive and
its automated coverage. Keep product docs honest about planner versus provider
I/O and status-only prototypes versus durable effects. Run Docs Center
freshness, integrity, unit, and browser tests before merging.