Beyond private bot chat, Oshun models Telegram broadcast channels, inline results, files/media, Mini App/deep-link navigation, and upgrade/payment state. These surfaces share policy and provenance but use different Telegram APIs, audiences, privacy assumptions, and delivery evidence.
The context determines audience and API shape. A private capability does not become group- or channel-safe, and a call plan is not delivery until Telegram's application response is inspected.
Editorial Telegram channels#
telegram-channel is the editorial broadcast target for curated Tara, Arete,
Nyx, and Nisaba content. An editorial post carries channel/domain, content and
source/provenance, disclosure, schedule/publication identity, review/policy
state, and immutable version.
The publishing module can synthesize a Telegram-ready post and model scheduled publication/takedown. The actual operator flow also needs:
- registered channel/chat identity and bot administrator permissions;
- tenant/editorial allowlist and environment separation;
- review/approval/embargo and idempotent schedule;
- Bot API send/edit/delete composition and application response;
- delivery message id, timestamps, failures/retries, and audit;
- correction/replacement/takedown relation to the original;
- safe text/media limits and rights for public distribution.
The channel is deliberately not crisis-capable. A public post cannot be used as personal crisis delivery. Member preference/binding is not the authorization for editorial publication.
Admin discovery and configuration live at
apps/oshun/admin/src/app/messaging/telegram-channels; browser coverage lives
in apps/oshun/admin/e2e/telegram-channel-registry.spec.ts. The operator
walkthrough is
Messaging · Telegram channels.
Inline mode#
Inline queries let a member invoke the bot from another chat and choose a bounded share card. Builders create:
- attributable share cards with stable result id, title/description/body, deep link, and disclosure/provenance;
- Sophia grounded results that preserve evidence/abstention semantics;
- no result or safe refusal for abuse, unauthorized/private data, unavailable evidence, or content that cannot be shared.
Telegram caps result count and result-id bytes. Result ids are deterministic enough for caching/idempotency without embedding sensitive content. Inline queries are rate/abuse limited and never expose personal library, settings, reminders, account, payment, or restricted source state.
Selecting an inline result is a Telegram-side share, not an Oshun durable save unless a separate callback/effect succeeds. Attribution links use the closed deep-link vocabulary.
Text, files, photos, and voice delivery#
The delivery translator turns a BotResponse into Bot API calls. It handles:
- plain/grounded text, safe parse mode, disclosure and provenance;
- message splitting within Telegram's text limit;
- inline keyboard attachment and callback-data limits;
- Telegram file ids versus upload/downloadable media references;
- photos/documents/voice forms declared by the response;
- chat actions and callback answers through their specific methods;
- multiple calls and partial failure reporting.
Media references are untrusted. Downloads/uploads use allowlisted schemes and destinations, bounded size/time/type, no token leakage on redirects, and validated provider responses. A source's rights must permit the intended private/group/public delivery. File ids and provider URLs are identifiers, not permanent proof of ownership or availability.
Telegram may answer HTTP 200 with {ok:false}; application body decides
success. Rate-limit/retry-after, blocked/forbidden chat, invalid entity/markup,
oversized content, missing file, and transient server/network failures are
classified separately. A multi-part response is not globally successful when one
required part failed.
Start deep links#
https://t.me/<bot>?start=<payload> maps a closed, bounded payload to a
command. Current mappings cover ritual/sit, check-in, tonight/sky, passage/read,
library, continue/resume, streak, settings, ask, and upgrade aliases. Unknown,
malformed, or stale payloads fall back to the greeting instead of becoming
arbitrary commands.
The bot username is normalized safely; payloads only use Telegram's allowed character set and maximum length. Deep links do not carry member ids, resource secrets, session tokens, raw URLs, or payment data. The member still passes command scope, binding, authorization, policy, and availability checks after arrival.
Mini App buttons#
Private chats can carry Web App buttons to a curated Mini App surface. Telegram
does not allow the same affordance everywhere, so group contexts use a known
start deep-link fallback where one exists. Missing mapping means the button is
omitted rather than pointed at a generic screen that cannot perform its label.
The Mini App base origin is configured/deployed; link builders allow only known surface slugs and safe origin/URL construction. Opening a button is navigation, not authentication—the Mini App still verifies initData and obtains a scoped session.
Upgrade flow#
/upgrade delegates to a typed upgrade port. Possible outcomes include a ready
link/invoice choice, unavailable/not connected, ineligible/denied, invalid, or
failed. Upgrade copy and buttons follow the actual outcome and keep the payment
provider/rail explicit.
The current command description identifies a crypto upgrade path, and BFF/ payments-bridge code owns the customer-surface routing. The Telegram platform also has typed invoice/payment lifecycle utilities. These are related but must not be conflated: a generic Telegram invoice planner is not proof that the live Oshun upgrade command uses Telegram fiat payments.
Telegram invoice lifecycle#
The modeled lifecycle covers:
- Create invoice request with stable product/order/member/currency/amount and provider payload identity.
- Send invoice through a configured Telegram/payment composition.
- Receive and validate pre-checkout query; re-check order, amount/currency, inventory/entitlement, user/binding, expiry, and duplicate state.
- Approve or reject within Telegram's deadline with safe copy.
- Receive successful-payment update; verify identifiers and amount/currency, claim idempotently, and grant entitlement through the real billing system.
- Persist receipt/provider charge identity and audit.
- Handle refund/reversal through the configured provider, reconcile entitlement, and notify accurately.
Bot payloads are opaque, signed/unguessable or server-resolved references—not a client-authoritative price or entitlement. A successful Telegram payment update does not directly edit plan state without billing verification and idempotency.
Payments safety and privacy#
- Keep provider tokens, invoices, charge ids, and receipts out of ordinary message logs and durable chat memory.
- Never request card, seed phrase, private key, or payment secret in chat.
- Personal upgrade/payment commands are private-chat-only.
- Use the member's actual entitlement, country/currency/rail availability, and current price at pre-checkout, not only invoice creation.
- Separate provider acceptance, billing/entitlement application, receipt delivery, and refund state; expose pending/recovery when they diverge.
- Reconcile duplicate/reordered update delivery and partial outages.
Cross-domain and V3 links#
Telegram deep links and reminders can re-enter V1 member rooms and V3 session experiences where the target product owns a safe public route and the member passes identity/entitlement checks. Link construction names intent/surface, not raw internal database identity. The target shows its own disclosure, memory, rights, and safety state.
Verification#
- Editorial create/review/schedule/send/edit/correct/takedown with admin role, provider response, retry, and audit.
- Inline result limits, stable ids, attribution, grounding, abuse, and absence of private content.
- Text splitting, multibyte callback/id limits, keyboard/media construction, upload/download failure, Bot API application errors, and partial delivery.
- Deep-link allowed/alias/unknown/malformed/maximum/bot-addressed routes and post-arrival authorization.
- Private Web App button and group fallback/omission behavior.
- Upgrade outcomes and, if deployed, invoice/pre-checkout/payment/entitlement/ refund idempotency and failure reconciliation.
Primary shared modules are publishing.ts, inline.ts, deliver.ts,
deep-links.ts, keyboard.ts, upgrade.ts, and payments.ts under
libs/oshun/messaging-channels/src/telegram.