daniilganievdaniilganiev/telegram-dev/skills/telegram-mini-app/SKILL.md

telegram-mini-app

Skill0 starsChanged 36 days agoMITView on GitHub

Build Telegram Mini Apps (Web Apps) — BotFather setup, launch methods and start_param, the Telegram WebApp SDK and tma.js, theming, safe areas, full-screen, storage, haptics, validating initData on a TypeScript or Python backend, Stars purchases from the app, and wallet connection. Use this skill whenever the user works on an app inside Telegram, a Telegram Web App, Telegram.WebApp, tma.js, initData, a menu button that opens a web page, a Telegram game in the browser, or says "app inside Telegram" or "connect wallet in Telegram".

2 other projects use a version of this.

Adopted by

Most recently taken up by

xfstudio/skillstheir own version, first seen Oct 13, 2026
ai4brands-design/claude-skillstheir own version, first seen Mar 22, 2026

Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
xfstudio/skills★ 9same name
ai4brands-design/claude-skills★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository11 other files it gives its agents.
- add-paymentsSkill
- add-ton-connectSkill
- audit-projectSkill
- deploy-testnetSkill
- new-botSkill
- new-mini-appSkill
- telegram-botSkill
- telegram-devSkill
- telegram-launchSkill
- telegram-paymentsSkill
- telegram-tonSkill

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Keep the bot token, API keys and any backend secret out of the front-end bundle.
line 40

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Telegram Mini App

Stack

From scratch: an official Telegram Mini Apps template (React, Next.js, Vue, Solid) on @tma.js/sdk, or plain telegram-web-app.js for a small page.
With a TON contract: Acton --app already gives Vite + React + TON Connect; add the Telegram layer on top (see telegram-ton).
Backend in any language. The only hard requirement is validating initData there.

These SDKs change often; check the current package docs before writing integration code.

Setup

Bot in @BotFather (/newbot); token only in a backend env var.
Mini App via /newapp, or set the bot's menu button to the app URL.
HTTPS hosting; a tunnel (ngrok, cloudflared) for local development.
Telegram has a separate test environment (own accounts and bots) for testing payments and flows without real Stars.

Rules

Never trust client data. initDataUnsafe is for display only. Send raw initData to the backend and validate it: references/init-data-validation.md (TypeScript and Python).
Money and entitlements live on the server. CloudStorage, DeviceStorage and SecureStorage are conveniences, not a source of truth.
Digital goods in the app are paid in Stars: create the invoice link on the server and open it with openInvoice (telegram-payments). Do not add a crypto checkout for them.
Cross-origin hardening (Bot API 10.2): since 20 July 2026 Mini App methods can't be called from origins other than the app's own domain. An iframe or embedded third-party page that used to call Telegram.WebApp will silently stop working. The owner can opt out in @BotFather but then takes responsibility for every link in the app; don't recommend opting out.
Respect theme params (CSS variables) and both safe-area insets; test on iOS, Android, Desktop and the Web clients (WebK and WebA). Full-screen mode changes the insets.
Keep the bot token, API keys and any backend secret out of the front-end bundle.

Wallets

Connecting a TON wallet, signing transactions and proving wallet ownership are covered in telegram-ton (TON Connect, ton_proof). Show a visible network badge while on testnet.

References

references/init-data-validation.md — server-side validation, TS and Python, common mistakes.
references/webapp-features.md — launch methods, storage tiers, tma.js, TON Connect settings.

Related skills: telegram-bot (bot, webhooks, deep links), telegram-payments (Stars), telegram-ton (wallets, tokens), telegram-launch (checklist before release).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free