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 | 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 | 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 | 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 | 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 | 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 | 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 | Configuration/secrets, webhook registration, command discoverability, update dedupe/claiming, send cycle, delivery receipts, blocked users, scheduled cycle, health, tests, release, and incidents. |
Surface map#
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. The Telegram-specific canonical technical narrative is Telegram Surfaces.
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.
/startpayload 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.
Reading paths#
Product/support: read bot and commands, rooms/reminders/voice, and Mini App and linking.
Engineering: read architecture, trust, and operations.
QA/release: use the same three engineering topics plus the Telegram walkthrough and the assistant-delivery journey.
Canonical sources#
- Telegram Surfaces — V1 product and implementation narrative.
- Telegram buildout/audit plan — chronological defects, fixes, deployment findings, and remaining facts.
- Telegram Mini App walkthrough — route/view interaction and gap inventory.
libs/oshun/messaging-channels/src/telegram— channel contracts and pure behavior.apps/oshun/bff/src/telegramandapps/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, andapps/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.