Telegram Mini Apps

Telegram Mini Apps

Use this skill to design, implement, or review Telegram Mini Apps as production systems. Treat a Mini App as bot + frontend + backend, not as a standalone trusted webpage.

Core Rule

Do not trust the frontend. initDataUnsafe is for client convenience only. Sensitive decisions start after backend validation of raw initData, auth_date, and the correct signature path.

Hierarchy And Handoffs

This is a vertical product skill: start here for a Telegram Mini App because its bot, WebView, authentication, payments, and platform constraints change otherwise generic web or service decisions. It owns the Telegram-specific contract across frontend, bot, and backend.

Delegate a non-Telegram backend's topology, storage, queues, and capacity to $system-design; use $software-engineering for codebase lifecycle and $qa-testing for general verification. Keep Telegram auth, client behavior, payment, and BotFather decisions here so generic skills do not override platform rules.

Use $web-frontend-engineering for generic browser state, rendering, and loading implementation, carrying the Telegram WebView and lifecycle constraints from this skill. Use $application-security-engineering for general application-control design and remediation, while retaining Telegram-specific initData validation, authentication, and payment rules here.

Reference Routing

Read only the references needed for the current task.

• Always start with references/01-overview.md for broad design, implementation, or review.
• For launch entry points, startapp, sendData, query_id, and lifecycle, read references/02-launch-modes-and-lifecycle.md.
• For auth model, initData, initDataUnsafe, session strategy, and trust boundaries, read references/03-auth-initdata.md.
• For HMAC, Ed25519, signature, hash, TTL, and library validation, read references/04-backend-validation.md.
• For bot/frontend/backend boundaries, API shape, business logic, and system architecture, read references/05-frontend-backend-architecture.md.
• For official WebApp API, @tma.js/*, React/TypeScript setup, and feature detection, read references/06-sdk-api-and-native-capabilities.md.
• For Telegram-native UI, buttons, events, theme, viewport, fullscreen, safe areas, and mobile UX, read references/07-ui-theme-viewport.md.
• For CloudStorage, DeviceStorage, SecureStorage, biometrics, location, and sensors, read references/08-storage-biometry-sensors-location.md.
• For invoices, Telegram Stars, XTR, payment providers, pre_checkout_query, /paysupport, and fulfillment, read references/09-payments-and-stars.md.
• For local development, test environment, HTTPS tunnels, mocks, and WebView debugging, read references/10-testing-debugging-local-dev.md.
• For release hardening, BotFather settings, secrets, observability, QA, and rollout, read references/11-deployment-production-checklist.md.
• For audits and pre-release review, read references/12-common-mistakes.md.
• For creating or updating this skill, read references/13-future-skill-outline.md.

Workflow

1. Classify the request:
   • New Mini App design: read 01, 02, 03, 04, 05, 06, 07, 10, 11; add 09 if payments are in scope.
   • Code implementation: read the topic file for the touched layer, plus 03 and 04 for auth-sensitive code.
   • Security/auth review: read 03, 04, 05, 11, 12.
   • Frontend/UX review: read 06, 07, 10, 12.
   • Payments work: read 05, 09, 10, 11, 12.
   • Native capabilities/storage/biometry/sensors/location: read 06, 08, 10, 12.
   • Testing/debugging: read 02, 06, 07, 10.
   • Production readiness review: read 03, 04, 05, 09 if payments, 10, 11, 12.
2. Identify blocking unknowns: launch mode, backend stack, auth/session strategy, payment type, target clients, and deployment environment. Ask only when the answer changes implementation or risk.
3. Prefer the project's existing framework and SDK choices. If none exist, recommend a conservative stack: bot + backend API + mobile-first frontend, with official Telegram docs as source of truth and @tma.js/* where TypeScript ergonomics help.
4. Separate facts from engineering advice when docs are not explicit. Mark current-version claims as requiring fresh verification if Telegram Bot API, payments, or SDK compatibility matter.
5. Validate every design against auth, backend ownership, launch mode constraints, WebView behavior, feature detection, payments, observability, and release/rollback.

Output For New Design

Include:

• Product scope, target Telegram clients, launch modes, and non-goals.
• Bot/frontend/backend architecture and ownership boundaries.
• Auth flow with raw initData, backend validation, TTL, and session strategy.
• Data model/API sketch and server-side business rules.
• Frontend SDK/API choice, theme/viewport/buttons/events plan.
• Native capability plan with feature detection and fallbacks.
• Payment flow if relevant, including Stars vs physical goods distinction.
• Local dev, test environment, WebView debugging, and real-device QA plan.
• Production checklist: HTTPS, BotFather settings, secrets, observability, rate limit, rollout, support.
• Risks, assumptions, and next validation steps.

Output For Review

Lead with risks and missing decisions:

• Critical trust/auth flaws.
• Missing backend validation or weak session strategy.
• Wrong assumptions about launch mode, sendData, startapp, or query parameters.
• SDK/API compatibility and feature-detection gaps.
• UI/theme/viewport/safe-area regressions.
• Storage/biometry/sensor/location misuse.
• Payment fulfillment and Stars/provider mistakes.
• Local/dev mocks leaking into production.
• Missing real-device/WebView QA, monitoring, rollback, or support process.

Coding Quality Bar

• Never put bot tokens, provider tokens, or validation secrets in frontend code.
• Never authorize sensitive actions from initDataUnsafe, URL params, or client-only state.
• Prefer a maintained validation library when available; if implementing HMAC/Ed25519 manually, use strict parsing, correct data-check-string construction, TTL, and constant-time compare.
• Guard Telegram WebApp calls with support/version checks and fallbacks.
• Use Telegram theme params and viewport/safe-area data instead of assuming browser dimensions.
• Keep browser mocks dev-only and impossible to enable accidentally in production.
• Fulfill payments only after server-side successful_payment, never after openInvoice UI state or pre_checkout_query alone.

Currentness Guardrail

Telegram WebApp API, Bot API payments, and @tma.js/* evolve. For current API names, SDK versions, payment rules, or platform requirements, verify against official Telegram docs and the relevant SDK docs before finalizing implementation.