# Telegram Mini Apps > Use when designing, building, reviewing, validating, debugging, deploying, or operating Telegram Mini Apps and Telegram Web Apps. Trigger for Telegram bot + mini app architecture, launch modes, BotFather setup, initData authentication, backend validation, HMAC/Ed25519 checks, tma.js, Telegram WebApp API, native buttons, theme/viewport/safe area, CloudStorage/DeviceStorage/SecureStorage, biometrics, sensors, location, Telegram Stars/payments, WebView testing, mobile debugging, production readiness, security reviews, and long-term maintenance. - Skill: `bejeweledme/telegram-mini-apps` (Agent Skill, multi-file: 16 files) - Install (CLI): `npx skillmds@latest add bejeweledme/telegram-mini-apps` - Raw SKILL.md: https://api.skillmd.com/api/skills/bejeweledme/telegram-mini-apps/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: BejeweledMe (https://skillmd.com/u/bejeweledme) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/bejeweledme/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.