# Telegram Safety, Privacy, Grounding, and Rights

Telegram is an external, global chat platform. Oshun treats it as a
purpose-limited member channel with verified opt-in, narrow content classes,
minimal durable ingestion, explicit grounding/disclosure, private/group
separation, and fail-closed provider boundaries.

```mermaid
stateDiagram-v2
  [*] --> UpdateReceived
  UpdateReceived --> Rejected: webhook secret or update validation fails
  UpdateReceived --> Claimed: durable dedupe succeeds
  Claimed --> ScopeDenied: tier binding chat or personal-command boundary fails
  Claimed --> CrisisReview: inbound content admitted for safety check
  CrisisReview --> CrisisResponse: crisis policy triggers
  CrisisReview --> Grounding: ordinary question or room intent
  Grounding --> Abstained: evidence unavailable or unauthorized
  Grounding --> PolicyAdmitted: evidence and channel policy pass
  PolicyAdmitted --> EffectPending: save reminder preference payment or delivery
  PolicyAdmitted --> ResponseReady: read-only grounded response
  EffectPending --> ResponseReady: durable effect receipt succeeds
  EffectPending --> Failed: denied unavailable partial or provider failure
  ResponseReady --> Delivered: Telegram accepts required calls
  ResponseReady --> Failed: Telegram rejects or delivery is partial
  CrisisResponse --> Delivered
  Delivered --> Audited
  Abstained --> Audited
  ScopeDenied --> Audited
  Failed --> Audited
  Rejected --> [*]
  Audited --> [*]
```

Private/group context, grounding, crisis behavior, durable effects, provider
delivery, and audit remain independent controls. Passing one never implies the
others.

## Audience and channel-policy guard

The channel dispatcher allows messaging only for contemplative and curated
creator tiers. AAA creator and operator/admin traffic is suppressed before a
Telegram channel is selected. That prevents confidential builder, generation,
review, source, or operational content from leaking to chat simply because an
intent requests Telegram.

Each Telegram channel declares capabilities, residency, consent, retention,
disclosure, crisis capability, and allowed content classes. The bot and Mini App
can serve appropriate grounded-answer, ritual-reminder, identity-verification,
and crisis behavior. Broadcast channel policy is different and deliberately not
crisis-capable.

Routing also evaluates tenant allowlist, member opt-in/binding, residency,
required capability, content class, quiet hours, frequency cap, crisis state,
and available content variant. Suppression names a reason and produces no
provider call.

## Private, group, and public contexts

| Context          | Allowed posture                                                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Private bot chat | Member-specific rooms, settings, reminders, save, binding controls, upgrade, voice, grounded questions—subject to binding/authorization/policy. |
| Group/supergroup | Only content safe for the shared chat, such as a passage or grounded answer; personal commands are blocked at runtime.                          |
| Inline mode      | Shareable, attributed, non-personal result cards; no private state or restricted evidence.                                                      |
| Telegram channel | Reviewed editorial broadcast; no personal support/crisis delivery or member-state content.                                                      |
| Mini App         | Protected member content only after verified initData, scoped session, resource authorization, and appropriate UX disclosure.                   |

Chat id and Telegram user id are distinct. In groups, the requester, chat,
message/callback, and target member/resource are all validated. A group admin
role is not an Oshun member/tenant role.

## Consent and binding

Delivery requires a durable verified binding/opt-in, not a guessed username or
historical chat id. Consent records notice/version, channel, purpose/content
classes, time, source, and withdrawal. `/stop`, web unlink, and Telegram block
state have real delivery consequences; a member has a supported `/resume` or
relink path where appropriate.

Quiet hours and frequency caps implement member expectations but do not erase
queued state silently. Crisis routing has explicit policy exceptions only for a
crisis-capable direct channel, never public broadcast.

## Grounded Sophia answers

`/ask` sends a bounded question and request context to the Sophia grounder. A
valid answer includes evidence/citations, provenance bundle, grounding state,
and disclosure. Telegram rendering preserves a plain-text provenance footer and
source buttons when possible; channel limitations must not turn an unsupported
claim into a confident answer.

The grounder abstains when evidence is absent, inaccessible, contradictory
beyond policy, below the required grounding state, or the adapter is not
configured. The bot uses explicit abstention copy rather than filling the gap
from general model knowledge.

Citations are permission-safe and stable links or references. A button cannot
expose a private source to another group member or create access merely by being
rendered. If evidence is too sensitive or the channel cannot preserve needed
context/disclosure, the answer is withheld or redirects to an authorized
surface.

## Crisis-aware behavior

Inbound text/voice transcript is checked against crisis policy before ordinary
persona flourish or tool actions can continue. Crisis response is supportive,
direct, locale/region-aware where configured, avoids pretending to be emergency
services, and surfaces appropriate immediate resources. It does not diagnose,
promise secrecy, or rely on a public Telegram channel.

Only crisis-capable direct channels may receive crisis-hotline intent. Crisis
policy can bypass ordinary quiet hours/frequency suppression but never tenant/
identity/channel capability, privacy, or provider security boundaries. Crisis
content is minimized in logs and durable memory.

## Durable memory ingestion

Chat content does not automatically become Iris memory. The boundary decision
requires member opt-in, an eligible direct channel (`telegram-bot` or
`telegram-miniapp`, never `telegram-channel`), allowed purpose/content, and
redaction.

Channel-specific redaction removes Telegram usernames, callback data, raw
initData, Mini App session tokens, handles, phone/payment tokens, and other
transport secrets. Session conversation needed to answer a request remains
distinct from durable profile memory. Voice audio/transcripts, crisis content,
payment data, group messages, and restricted evidence receive stricter or
no-ingestion treatment.

## Audit and provenance envelope

Responses carry a channel audit envelope with channel, recipient/chat context,
intent/content class, persona/policy version, provenance bundle, residency,
retention, disclosure verification, correlation/update identity, and outcome.
The envelope does not copy full message/source content by default.

Bot receive/send/suppression, channel schedule/send/takedown, auth/binding,
payment, and preference/deletion events use their specific audit vocabulary.
Provider application errors and partial delivery remain visible; a planned
response is not a send audit.

## Webhook and update security

- Use HTTPS and verify the configured Telegram webhook secret header with
  constant-time comparison.
- Bound request size/content type and parse only accepted update shapes.
- Claim and deduplicate update ids durably before effects; handle retries,
  concurrency, edited messages, callbacks, membership, and payments without
  duplicate writes.
- Keep bot tokens out of route parameters/logs and restrict provider egress.
- Validate callback namespaces/byte limits and re-authorize action targets.
- Rate-limit actor/chat/update classes before costly providers; detect inline
  abuse.
- Treat Bot API HTTP 200 `{ok:false}` as failure and classify blocked/
  forbidden/rate-limited/transient outcomes.

## Mini App and Login security

Server-side verification checks signature and freshness for Login Widget and
Mini App initData. Mini App sessions are short-lived, signed, audience/scope
restricted, and invalidated by unlink/revocation. Protected APIs re-authorize
the Oshun resource and can require primary credentials for sensitive actions.

CORS allowlists the deployed Mini App origin but is not authentication. Raw
initData, hashes, bot token, session/binding tokens, and profile payloads are
redacted. See
[Mini App, authentication, and account linking](./mini-app-auth-and-account-linking.md).

## Voice and file safety

Voice/media download uses Telegram file identity only through the configured Bot
API, with type/size/time/redirect/host limits. STT/TTS providers receive minimum
necessary content, have declared retention/training policy, and return versioned
results. Transcripts are untrusted input and run through the same safety,
grounding, and command controls as typed text.

Public/channel file publishing requires explicit distribution rights. A file
received privately does not become reusable in inline or broadcast output.

## Payments and sensitive actions

Payment/upgrade is private-chat-only and separates invoice, pre-checkout,
provider acceptance, entitlement, receipt, and refund. Never solicit payment
secrets in chat. Price/currency/order/user and replay are validated server-side.
Binding, account, security, or billing changes may require the primary Oshun
credential despite valid Telegram identity.

## Retention, access, export, and deletion

Channel records declare retention for binding/consent, delivery and update
dedupe, reminders/preferences, audit, message content, voice/media, provider
receipts, and payment state. Store only the content needed for the declared
purpose.

Member data access/export describes Telegram bindings, preferences/reminders,
durable memory admitted from Telegram, and relevant receipts/audit without
including secrets or other chat members' data. Unlink/deletion revokes sessions
and delivery, reclaims eligible content/projections, preserves required minimal
fraud/security/audit facts, and tracks provider/external residuals.

## Safety verification

- Tier, content-class, opt-in, tenant, residency, capability, quiet-hour,
  frequency, and crisis routing matrices.
- Private/group/channel/inline separation and no personal-data existence leaks.
- Grounded answer, citations, contradiction, unavailable evidence, abstention,
  disclosure, and unauthorized-source cases.
- Crisis trigger and false-positive/negative governance, voice transcript path,
  locale/resource behavior, privacy, and no public-channel routing.
- Durable-memory opt-in/channel/redaction/retention/deletion cases.
- Webhook secret, malformed/oversized update, dedupe/claim concurrency, callback
  authorization, rate/abuse, blocked user, and Bot API errors.
- Login/initData freshness/signature/scope/revocation, binding collision, and
  primary-credential challenges.
- Voice/file bounds/provider failures and payment replay/amount/entitlement/
  refund reconciliation.

Canonical details live in
[Telegram Surfaces](../../features/telegram-surfaces.md),
[messaging-channel architecture](../../architecture/messaging-channels.md), and
the Lilith
[identity, memory, safety, and rights handbook](../../../V3/docs/lilith/identity-memory-safety-and-rights.md).