How to build a Telegram Mini App
A Telegram Mini App is an ordinary web app that opens inside Telegram, attached to a bot. If you can build a web page, you can build a Mini App: Telegram adds a JavaScript bridge that gives you the user's identity, theme colours, buttons, haptics and payments. This guide walks through a minimal Telegram Mini App example, the SDKs, templates and no-code builders you can start from, payments with Telegram Stars and TON Connect, ads and monetization inside Mini Apps, and the one security step every Mini App needs: validating initData on the server.
Telegram's Bot API and Mini App features change often. Treat this as an overview and check the official Telegram documentation for current method names and limits.
What a Mini App is technically
Under the hood a Mini App is a web page served over HTTPS and opened in Telegram's in-app web view. It is launched from a bot: from the menu button, an inline button, a direct link or the bot profile. Telegram passes launch parameters to the page, including signed data about the user, and exposes a JavaScript object, window.Telegram.WebApp, for interacting with the Telegram interface. If you have never built a bot, start with Telegram bots.
A minimal example: bot, URL and the WebApp script
- Create a bot with @BotFather and save the token.
- Host a simple HTML page on any HTTPS host.
- In BotFather, set your page URL as the bot's Mini App or menu button.
- Open the bot in Telegram and tap the button.
<script src="https://telegram.org/js/telegram-web-app.js"></script>
<script>
const tg = window.Telegram.WebApp;
tg.ready();
tg.expand();
document.body.style.background = tg.themeParams.bg_color;
const name = tg.initDataUnsafe.user ? tg.initDataUnsafe.user.first_name : "guest";
document.body.textContent = "Hello, " + name;
</script>
That is a working Mini App. Everything else, from routing to state management, is regular front-end development.
SDKs, templates and no-code builders
| Option | Good for |
|---|---|
| Official telegram-web-app.js | Small apps, full control, no build step |
| Community SDKs for React, Vue and others | Typed wrappers, hooks, routing helpers |
| Templates on GitHub | A ready project with bundler, theme and TON Connect wired up |
| No-code Mini App builders | Simple shops and forms without code; less flexibility |
For inspiration on what people build, see Telegram games and Mini Apps.
Payments with Stars and TON Connect
For digital goods and services sold inside Telegram, Telegram requires payment in Telegram Stars. The bot creates an invoice in the Stars currency, the Mini App opens it, and Telegram handles the payment and notifies your bot. Stars earned can later be converted by the developer through Fragment, subject to Telegram's rules: Telegram Stars. Separately, TON Connect lets users connect their own TON wallet to your app, for example to sign a transaction or prove wallet ownership. TON Connect is for on-chain actions, not a replacement for Stars when selling digital goods.
Ads and monetization inside Mini Apps
Besides Stars sales and subscriptions, many Mini Apps show ads through third-party ad networks built for Telegram, or sell sponsored placements and channel promotions. Rewarded formats work well in games but need anti-fraud logic, because bots and farms target any reward. Be careful with "earn" mechanics: promising users money attracts abuse and regulatory attention. Some patterns used by earning bots are covered in Telegram earning bots.
Security: validating initData
Never trust initDataUnsafe on the server. Send the raw initData string to your backend and verify it: build a data-check string from the sorted key-value pairs without the hash, derive a secret key with HMAC-SHA256 using the string WebAppData and your bot token, compute the HMAC of the data-check string and compare it with the hash. Also reject data whose auth_date is too old. Only after this check should you treat the user ID as authentic and grant rewards or access.
A Mini App example in the wild
TotalHash is a free mining game built as a Telegram Mini App. Tasks send small amounts of USD₮ and GRAM to a TON wallet. No earnings promised.
Free game in Telegram.
Open TotalHashFAQ
What is a Telegram Mini App?
A web app served over HTTPS that opens inside Telegram, attached to a bot.
Is there an official Telegram Mini App SDK?
Telegram provides the telegram-web-app.js script; community SDKs add framework wrappers.
How do payments work in Mini Apps?
Digital goods are paid in Telegram Stars; TON Connect is for wallet actions.
How do I verify the Telegram user in a Mini App?
Validate the initData hash on your server with HMAC-SHA256 and your bot token.