Mini Apps
A screen inside the conversation
A Telegram Mini App is a web page rendered inside Telegram, launched from a bot, that receives a signed `initData` string identifying the user. That signature is the whole value: it removes the login step from a checkout entirely, because the app already knows who is looking at it before it renders a single pixel.
Telegram Mini App builds: what this section covers
- Identity
- Signed initData, HMAC-SHA256 against a key derived from the bot token
- Validation
- Server-side only. A client-side check proves nothing
- Viewport
- Reports its own height; expands on user gesture, not by default
- Storage
- Webview storage and cookie behaviour differ across iOS and Android
- Reach
- Telegram users only. No search discoverability, ever
- Payments
- Telegram Stars for digital goods; a provider or TON for everything else
As of 2025-10-01, Telegram Bot API 13.4
Why a Mini App rather than a chat flow
A bot conversation is a good interface for a handful of decisions and a bad one for twenty. Once a customer needs to compare four items, filter a catalogue, or see a total update as they change quantities, the message-and-button format stops helping and starts fighting. A Mini App is Telegram's answer to that: a real webview, opened from the same chat, that closes and hands its result back to the bot.
What makes it different from simply linking out to a website is the identity. Telegram passes the app a signed payload naming the user, and a server that validates that signature knows exactly who is on the other end without a password, a magic link, or an OAuth round trip. On a web checkout the equivalent step costs conversions every time; here it does not exist.
The cost is reach and discoverability, and both are absolute. A Mini App reaches people who are in Telegram and nobody else, and it will never appear in a search result. That is the trade this section exists to help you decide, and the comparison pages below argue it in both directions rather than only the flattering one.
Selling inside the chat
The builds where the Mini App is the product surface rather than a convenience — a catalogue, a cart and a payment, all inside the chat the customer is already in.
The full commerce surface — catalogue, cart, checkout and chain settlement — is
For a menu with modifiers, where the density argument is at its strongest, see
Interfaces a conversation cannot carry
Cases where the reason for a Mini App is purely interface density: a menu with modifiers, a slot grid, a wallet balance that has to update while you look at it.
Balances that change while the user is watching them belong in a webview, which is why
A working example of the same pattern, running on this site as both a web page and a Mini App, is
What settles the money
What actually moves the money, and the category rules that decide which of them you are allowed to use. This is the part that most often changes a plan.
For digital goods, the rail with no merchant onboarding at all is
To let a customer pay from a wallet they already control, the protocol is
The pre-checkout timeout and the refund window are handled in
Whether a Mini App is the right shape at all
The arguments against, set out properly. Two of these three conclude that a Mini App is the wrong answer for a meaningful share of readers.
If the question is whether to build for the app stores at all, read
For the case where organic search matters more than checkout friction, see
The effort breakdown, including the shell and the signature validation, is in
What people ask before committing to a Mini App
Is a Mini App just a website in a frame?
Technically close, practically not. The difference is the signed initData: the page is handed a verified identity by the platform before it renders. That removes the entire authentication step, which on a normal checkout is where a measurable share of customers leave.
Can I validate the init data in the browser?
No, and treating it as a formality is the most common security mistake in this area. The signature is computed with a key derived from the bot token; putting that token in client code hands anyone the ability to forge an identity. Validation happens on the server, against the raw string, before anything is trusted.
Can a Mini App sell physical goods?
Yes, but not with Telegram Stars, which are restricted to digital goods and services. Physical goods need a payment provider you hold a merchant account with, or a chain rail. This catches more projects than any other single rule in this section.
Will a Mini App show up in Google?
No. It has no indexable URL and never will. If discovery through search matters to the business, the Mini App is the wrong primary surface and a web storefront with a bot alongside it is the better shape.
Does it work the same on iPhone and Android?
Broadly, with two practical differences worth designing around: the available storage and cookie behaviour inside the webview differ, and the viewport starts smaller than the screen and only expands on a user gesture. Both are cheap to handle deliberately and unpleasant to discover after launch.
Do I need a bot as well, or just the Mini App?
Both, always. A Mini App is launched from a bot and hands its result back to one; there is no standalone form. In practice the bot is also where notifications, receipts and support live, so it is rarely a burden.
Related reading
Every build listed here, with its exact figure and delivery window, sits in the full catalogue.
For the other surface that lives inside Telegram rather than beside it, see in-chat AI assistants.
The exact limits quoted above — signature validation, viewport, payload caps — are documented in the Bot API reference.
For what the effort actually goes on, read the cost breakdowns.