Telegram Mini App

Status: implemented as optional capability wrappers.

Linear: MIN-272, MIN-258

Source Check

Telegram Bot API 8.0 added Mini App support for fullscreen mode, persistent device storage, secure local storage, and home-screen shortcuts.

Primary source:

• https://core.telegram.org/bots/api-changelog

Repository Changes

• apps/telegram-miniapp/src/telegram-capabilities.ts wraps fullscreen, home-screen, DeviceStorage, and SecureStorage with feature detection.
• The Mini App stores only non-secret UI hints client-side:
  • last active tab in DeviceStorage;
  • workspace/user/session metadata in SecureStorage.
• The JWT remains in memory via setAuthToken; OAuth refresh tokens still belong behind server-side connectors and HELM-governed flows.
• The home dashboard exposes fullscreen and home-screen actions when Telegram reports support.

Boundary Notes

Mini App storage is not a replacement for PostgreSQL, Drizzle, connector token storage, or HELM approvals. External actions still enter through gateway/orchestrator and are governed before execution.

Public Mini App Checklist

The public Mini App docs should cover only the safe setup and user-facing integration path: Telegram Web App configuration, callback origin, login handoff, workspace selection, task creation, approval visibility, and error handling. Managed bot provisioning, webhook secrets, child bot token rotation, and production support flows belong in authenticated operator documentation. Keep examples focused on what a self-hosted developer can reproduce locally: configure the bot, open the Mini App, authenticate, create a task, confirm the task appears in the gateway, and verify that governed actions record audit/evidence metadata.

Expected Output

After setup, a developer should be able to open the Mini App from Telegram, receive a valid Telegram initData login, resolve a workspace, create or inspect a task, and see predictable errors for missing bot token, invalid origin, expired session, or unavailable gateway. Capture browser console output, gateway request ID, sanitized initData shape, and workspace ID for diagnostics. Never paste bot tokens, webhook secrets, raw Telegram user payloads, or managed support-bot routes into anonymous docs or LLM exports.

Browser And Mobile Checks

Include a simple smoke path for desktop Telegram, mobile Telegram, and browser preview. The expected page should fit small screens, preserve safe-area padding, recover from offline gateway errors, and show the same workspace/task state after reload. Public docs should name the diagnostic IDs to collect, while protected docs own bot provisioning, token rotation, support escalation, and child bot lifecycle details.

Audience Split

Founder guidance covers opening the Mini App, choosing a workspace, creating a task, reviewing approvals, and understanding why an action was blocked. Operator guidance covers environment variables, bot configuration, origin checks, gateway reachability, logging, and rollback to a browser-only workflow when Telegram is unavailable. Each section should name the visible success signal and the first safe diagnostic to collect.

Troubleshooting

If login fails, check bot token configuration, Telegram auth age, allowed origin, gateway logs, and workspace membership. If the Mini App renders but actions fail, capture the request ID, current workspace ID, task ID, response status, and sanitized payload shape. Do not include private Telegram user payloads or managed support-bot webhook details in public support artifacts.