playbooks

home / skills / omer-metin / skills-for-antigravity / telegram-mini-app

telegram-mini-app skill

/skills/telegram-mini-app

This skill helps you build Telegram Mini Apps with TON integration, leveraging Web App API, crypto payments, and viral UX to monetize.

npx playbooks add skill omer-metin/skills-for-antigravity --skill telegram-mini-app

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
1.6 KB
---
name: telegram-mini-app
description: Expert in building Telegram Mini Apps (TWA) - web apps that run inside Telegram with native-like experience. Covers the TON ecosystem, Telegram Web App API, payments, user authentication, and building viral mini apps that monetize. Use when "telegram mini app, TWA, telegram web app, TON app, mini app, " mentioned. 
---

# Telegram Mini App

## Identity


**Role**: Telegram Mini App Architect

**Personality**: You build apps where 800M+ Telegram users already are. You understand
the Mini App ecosystem is exploding - games, DeFi, utilities, social
apps. You know TON blockchain and how to monetize with crypto. You
design for the Telegram UX paradigm, not traditional web.


**Expertise**: 
- Telegram Web App API
- TON blockchain
- Mini App UX
- TON Connect
- Viral mechanics
- Crypto payments

## Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

* **For Creation:** Always consult **`references/patterns.md`**. This file dictates *how* things should be built. Ignore generic approaches if a specific pattern exists here.
* **For Diagnosis:** Always consult **`references/sharp_edges.md`**. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
* **For Review:** Always consult **`references/validations.md`**. This contains the strict rules and constraints. Use it to validate user inputs objectively.

**Note:** If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Overview

This skill is an expert guide and implementation assistant for building Telegram Mini Apps (TWA) that deliver native-like experiences inside Telegram. It covers Telegram Web App API, TON blockchain integration, user authentication, payments via TON Connect and crypto rails, and growth patterns for viral distribution and monetization. Use it to design, validate, and troubleshoot mini apps tailored to the Telegram UX and TON ecosystem.

How this skill works

I analyze your app concept and technical design against proven Mini App patterns, common failure modes, and strict validation rules used in production. I recommend concrete architecture, API usage, authentication flows, payment integration, and UX patterns optimized for Telegram Web App behavior. I also surface critical risks—privacy, session handling, payment reconciliation, and cross-platform quirks—and prescribe fixes and tests.

When to use it

  • Designing a new Telegram Mini App or porting a web app into Telegram
  • Implementing authentication and user identity via Telegram and TON Connect
  • Integrating crypto payments or on‑ramp/off‑ramp flows with TON
  • Optimizing UX and lifecycle for in‑chat, modal, and inline mini apps
  • Diagnosing production issues like session loss, payment failures, or platform incompatibilities

Best practices

  • Design for Telegram UX: keep flows short, avoid long redirects, and prefer async updates for in‑chat contexts
  • Use official Web App APIs for authentication and state; persist minimal server-side session data
  • Integrate TON Connect for wallets and crypto payments; ensure idempotent payment handling and server verification
  • Plan for edge cases: network drops, WebView resizes, repeated callbacks, and race conditions with payments
  • Instrument and validate every flow against strict rules: input validation, signature checks, and reconciled accounting

Example use cases

  • A social mini game that uses TON for in‑game purchases and viral invites to groups
  • A DeFi dashboard embedded in Telegram with wallet connect and quick trade UX
  • A utility bot that opens a mini app for premium features and collects crypto payments
  • A viral sticker or content generator that monetizes via one‑tap purchases and share hooks

FAQ

Can mini apps accept crypto payments inside Telegram?

Yes. Use TON Connect and server‑side verification to accept and reconcile crypto payments securely; design for idempotency and user feedback on transaction state.

How do I handle user identity and sessions?

Prefer Telegram Web App user info for initial identity, persist minimal server sessions, and revalidate signatures on reconnect. Combine with wallet auth for crypto actions.