In this article
A mini app is a web page that opens in a panel over your chat. No download, no account, no password — you tap something and you are inside a working application, already recognised.
That is the whole appeal and, read carefully, the whole risk. The friction that normally makes a person stop and think — installing, registering, choosing a password — has been removed, and what is on the other side is still somebody else's website, run by somebody you have not met.
What you will be able to do after this step
- check_circle Say exactly what a mini app can and cannot reach on your account.
- check_circle Read the frame around it, and notice when the frame is gone.
- check_circle Apply one rule that covers every mini app scam.
- check_circle Judge whether what you want to build belongs in this shape.
Four positions around the same panel
The answers differ sharply depending on whether you are opening one, worrying about one, building one, or paying inside one.
It is a web page, and the frame is the honest part
A mini app opens as a panel with Telegram's own header above it: the name of what you are in, and a way to close it. That header is the only part of the screen Telegram wrote. Everything below it was written by whoever runs the app, including anything that looks like an official notice, a warning or a system dialogue.
Minimising is not closing. The app keeps running with whatever you typed still in it, which is convenient for a game and the wrong state to leave a shop or a wallet in. Close the ones that matter deliberately.
Two habits carry over from earlier steps. The door you came through is the signal: an app reached from a bot's own menu is one you went looking for, and one reached from a link in a forwarded message is one somebody put in front of you. And an app that can occupy the whole screen has removed the header that told you where you were — decide whether you trust it before you hand it the screen, not after.
Treat a mini app the way you would treat a browser tab, not an installed application. Nothing in it is yours, and the only trustworthy pixels are the ones at the top.
What reaches it, and what does not
It gets who you are as Telegram identifies you — your account, your display name, your username and photograph if you have them — and it gets whatever you do inside it. That is the baseline, and it arrives automatically the moment the page opens.
It does not get your chats, your contacts, your messages or your phone number. There is no mechanism by which a page in that panel reads your conversations, and any app that appears to know something about them is either guessing or was told by you.
Anything further is a separate request you answer: writing to you in the chat, your location, your phone number, access to motion sensors, adding an icon to your home screen. Each is a prompt with a name on it, and each is a decision. The one worth being slowest about is location, because a single reading is an address.
The honest summary for somebody deciding: the exposure is bounded, and the bound is "a stranger knows this account used their app". For most apps that is unremarkable. For an app about something you would rather not be associated with, it is the thing to weigh.
Your conversations are out of reach. Your identity is not — and it is handed over at the moment of opening, before you have decided anything.
A website with two differences
If you are building one, almost everything you know applies: it is HTML, it runs in a browser engine, and it is served from your own hosting. Two things are genuinely different and both are worth designing around.
The person is already identified, and the identity arrives signed. Telegram hands the page a bundle describing who opened it, along with a signature your server can check using your bot's secret. The rule that follows is the one people get wrong: never trust the identity the page tells you — verify it on your server. A page can claim to be anybody; a correctly checked signature cannot.
The surface is a panel on a phone that can be swiped away. It opens partially expanded and can be enlarged, the keyboard shrinks it, and a downward gesture may close it entirely. Anything with a form, a game in progress or an unsent order needs to survive that — either by asking before closing or by saving as it goes. The most common complaint about mini apps is work lost to a gesture the user did not know was a gesture.
One thing to take advantage of: the panel inherits the reader's light or dark theme. Respecting it is the difference between an app that feels part of the client and one that is obviously a website in a box, and readers register that distinction as trustworthiness whether or not they could name it.
Verify on the server, and design for a surface that can vanish mid-sentence. Those two decisions separate a mini app from a website in a frame.
Where money is allowed to move
This is the tab with a rule rather than advice. Payment happens in Telegram's own payment sheet, which appears over the app; it does not happen in a form drawn inside the page. If an app asks you to type card details into its own layout, stop — not because it is certainly fraudulent, but because you have no way to tell, and the legitimate route exists precisely so that you do not have to judge.
The same logic, harder, for anything connected to a wallet: a mini app that asks for a recovery phrase, a private key or a Telegram login code is an attack every single time, with no exceptions and no benign version. Step 089 covers why the recovery phrase in particular ends the conversation.
And the rule from Step 077 holds its shape here. A legitimate transaction is one you started, by opening something and choosing to buy. An app that opens with a payment prompt, a connection request or a claim screen before it has shown you anything is telling you what it is for.
Telegram's sheet, or nothing. Any field inside the page asking for a secret is the whole scam, regardless of how well the page is made.
explore Why this shape exists at all
The interesting thing about mini apps is not the technology, which is ordinary. It is what removing the installation step does to who will try something.
A thing that requires downloading an application, creating an account and choosing a password loses the overwhelming majority of the people who were mildly interested. A thing that opens in two taps inside a conversation where somebody just mentioned it loses almost nobody. That is why this shape has succeeded for games, small tools, shops and ticketing, and why it has succeeded equally well for things that would not survive an app store review.
The design consequence for anybody building: you have been handed an audience with no patience and no commitment. The first screen has to be usable without explanation, because there is no onboarding sequence anybody will sit through and no installed icon to come back to. Mini apps that are ported from a website almost always fail on this alone.
And the consequence for anybody using: the absence of friction is not a statement about safety. Nobody reviewed it, nothing vetted it, and the two taps that got you in are the same two taps for the good ones and the bad ones.
touch_app Try it now — five minutes
Four steps, two for using and two for building.
- Open a mini app and look only at the header Read the name at the top. That line, and the close control beside it, are the only parts of the screen Telegram is responsible for.
- Minimise it and come back Notice that everything you typed is still there and the session never ended. Now decide which of the apps you use should be closed properly instead.
- If you build: test with the keyboard open The panel shrinks when the keyboard appears, and layouts that were designed on a desktop browser break exactly here.
- If you build: try swiping it away mid-form Whatever happens is what happens to your users. If work is lost, that is the first bug to fix.
rule When a mini app is the wrong answer
Three cases, all of which get built anyway.
When the answer is a sentence. A bot that replies with what you asked for is faster, works on every device, is searchable afterwards, and leaves a record in the chat. Wrapping that in a panel with a loading spinner makes it worse in every dimension. If the interaction is question in, answer out, the interaction is a conversation.
When people need it outside Telegram. A mini app lives in one application. If the same tool is also needed from a desktop browser, an email link or a colleague who does not use Telegram, you are building the thing twice and the mini app is the copy that will fall behind.
When it is a serious, repeated, long-session tool. The panel is small, dismissible and easy to lose. Anything somebody works in for half an hour a day wants a real window. The sweet spot for this shape is short, self-contained and occasional — buy a ticket, check a balance, play a round, fill in a form — and the further you get from that, the more you are fighting the surface.
help Common questions at this stage
Can a mini app read my messages?
No. It runs in a panel with no access to your conversations, your contacts or your message history, and there is no permission that grants it that. What it knows is the account that opened it and whatever you do inside it. If an app appears to know something about your chats, it was told — by you, or by a bot you gave rights to somewhere else — and that is a different question worth following up.
Does closing the panel log me out?
Not in the way you might hope. The app's own session behaves like a website's: reopening usually puts you back where you were, because the page recognises the account again the instant it loads. There is no universal "sign out of this mini app" control, which is a real gap. For anything holding money or an order, treat the app as always logged in and behave accordingly.
Is an app in Telegram's own listings safer than one from a link?
Somewhat, and not enough to switch your judgement off. A listing is a directory rather than a warranty, and popularity there measures promotion more than quality — apps that pay people to use them rank well. The more useful signal is the one from Step 087's neighbouring territory: whether you went looking for this or somebody put it in front of you. Nothing in a listing changes the rule about secrets.
What does "add to home screen" actually do?
It puts a shortcut on your device that opens the app directly. Nothing is installed and nothing new is granted, but you now have a door to a logged-in service sitting on your home screen, and removing the icon does not disconnect anything. Give it to the apps you deliberately open every day, and not to the one that offered you something for adding it — that offer is a distribution tactic rather than a convenience.
Can I build one without a bot?
No. A mini app is attached to a bot: the bot is what it is launched from, and the bot's secret is what makes the identity check possible. That means everything in Step 086 applies to you as well — the token is the credential, it never goes into the page's code, and the account that created the bot controls its future. Putting the token in the front end of a mini app is the single most common serious mistake in this area.
Do mini apps work on desktop and in the browser?
Generally yes, and they behave differently enough that testing on one is not testing. On a desktop client the panel is a window with a mouse and plenty of room; on a phone it is a sheet that shares the screen with a keyboard and can be dismissed by accident. Layouts built on a laptop and shipped without a phone test are the reason so many mini apps have a button just below the fold that nobody can reach.
At a glance
- 1A web page that knows you
A mini app is a website opened with your Telegram identity.
- 2What it cannot reach
Your chats, contacts and phone number are off limits; other access asks first.
- 3Payment rule
Pay only through Telegram's own payment sheet; never type cards or codes into a page.
Updated
