On this page
The essentials
- A mini app is a web page served over HTTPS, connected to a bot through the menu button or as the main Mini App in BotFather.
- The telegram-web-app.js script goes in the head before every other script.
- initDataUnsafe on the page cannot be trusted. The server validates initData with a signature derived from the bot token and checks auth_date.
- The bot token lives only on the server and never goes into the page's code.
- Before launch, test on iOS, Android and desktop: each platform has its own debug mode.
An Open button in a chat with a bot, and behind it a full app: a catalogue, a cart, a profile. It looks as if you need a special Telegram framework. In fact it is an ordinary web page that Telegram opens in its own window and hands data about the user.
Anyone who has built websites can build such a page. The difficulty lies elsewhere: the page also opens in an ordinary browser, where there is no Telegram at all. So what matters is not how good the interface looks, but whether the server checks that the user is real.
- 7 ways
- The number of ways to launch mini apps listed in Telegram's documentation.
- 4 platforms
- Where to test the app before launch: iOS, Android, Telegram Desktop and Telegram for macOS.
Preparation
What you need
- A bot in BotFather — the mini app is attached to it. How to create one is covered in "How to create a Telegram bot: BotFather, your first Python code, and one rule about the token".
- A page over HTTPS. Telegram opens a mini app at an address with TLS. Without it, only the test environment works.
- A server that keeps the bot token and validates the launch data. It can be the same server that runs the bot.
BotFather
Step 1. Connect the page to the bot
There are seven ways to open a mini app: the main button in the bot's profile, the menu button, a keyboard button, a button in a message, inline mode, a direct link and the attachment menu. Two are enough to start.
- The menu button. In BotFather: /setmenubutton or Bot Settings → Menu Button, then the page address. The button appears next to the input field in the chat with the bot.
- The main Mini App. In BotFather: /mybots → your bot → Bot Settings → Configure Mini App → Enable Mini App. A launch button appears in the bot's profile, and the app opens via the link t.me/bot_name?startapp.
Anything after startapp reaches the app in the start_param field — a way to open a specific section or pass an invite code.
Client code
Step 2. The page
Telegram's script goes in the head before any other script. The user data in initDataUnsafe is fit only for display; the raw initData string is what goes to the server.
<!doctype html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
<h1 id="hello">Loading…</h1>
<script>
const tg = window.Telegram.WebApp;
tg.ready();
// Display only: this data cannot be trusted
const user = tg.initDataUnsafe.user;
document.getElementById("hello").textContent =
user ? "Hello, " + user.first_name : "Open this page from Telegram";
// Send the raw string to the server for validation
fetch("/api/session", { method: "POST", body: tg.initData });
</script>
</body>
</html>Server code
Step 3. Validation on the server
The server checks that the initData string really came from Telegram. The algorithm from the documentation: all fields except hash are sorted by name and joined with line breaks as key=value. The secret key is the HMAC-SHA-256 of the bot token keyed with WebAppData. The signature of that string with the secret key must match the hash field. It is also worth checking auth_date so as not to accept stale data.
"""Validating a mini app's initData. Python 3.10+, standard library only."""
import hashlib
import hmac
import time
from urllib.parse import parse_qsl
def check_init_data(init_data, bot_token, max_age_seconds=3600):
fields = dict(parse_qsl(init_data, keep_blank_values=True))
received_hash = fields.pop("hash", "")
if not received_hash:
return None
data_check_string = "\n".join(
f"{key}={value}" for key, value in sorted(fields.items())
)
secret_key = hmac.new(b"WebAppData", bot_token.encode(), hashlib.sha256).digest()
expected = hmac.new(secret_key, data_check_string.encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, received_hash):
return None
if time.time() - int(fields.get("auth_date", "0")) > max_age_seconds:
return None
return fields # the user field is a JSON string with the user's dataIf the function returns None, the request is rejected. If it returns the fields, the data can be trusted: create a session and work with the user by their ID.
Important
Without validation, anyone can pose as anyone
A mini app's page can be opened in an ordinary browser with any name and any ID put into initDataUnsafe. If the server trusts that data without checking the signature, an attacker can sign in as another user and take their purchases or bonuses. Validate initData on the server at every sign-in, and never put the bot token in the page's code.
If the data needs to go to a third-party service without the bot token, initData includes a signature field: it is verified with Telegram's public key using Ed25519. Details are in Telegram's documentation.

Testing
Step 4. Debugging on three platforms
- iOS: tap the Settings icon in Telegram ten times and turn on Allow Web View Inspection. Connect the phone to a Mac and open Safari → Develop → your device.
- Android: turn on USB debugging; at the bottom of Telegram's settings, press and hold the version number twice and choose Enable WebView Debug. Open chrome://inspect/#devices in Chrome on your computer.
- Telegram Desktop on Windows and Linux: in the beta version, turn on Settings → Advanced → Experimental settings → Enable webview inspection, then right-click inside the app → Inspect.
- Telegram for macOS: in the beta version, click the Settings icon five times quickly and turn on Debug Mini Apps.
For experiments there is Telegram's test environment: it has its own accounts, its own BotFather, and links without HTTPS are allowed.
Checklist
Before launch
Payment rules are covered in detail in "How to accept payments in a Telegram bot: Stars, card or GRAM".
Questions
Can I build a mini app without my own server?
A static page can be hosted anywhere. But if the app stores anything, sells anything or gives out bonuses, it is defenceless without a server that validates initData: data on the page itself cannot be trusted.
What data about the user does a mini app receive?
The ID, name, username, language, Premium status and, if settings allow, the profile photo. It does not get the phone number or chats without a separate permission. More in "Telegram Mini App permissions: what you hand over when you tap Allow".
How do I get into Telegram's mini app catalogue?
Telegram may feature in the Mini App Store successful bots that have a main Mini App and accept payments in Stars. High-quality videos and screenshots in the bot's profile improve the chances.
A Mini App is a website that Telegram has given a window, a launch button and data about the user. Building the interface is not hard, and Telegram's documentation describes every step in detail.
The real work is on the server: checking the initData signature, checking the time and keeping the token to yourself. Do this from day one, and you can show the app to people with confidence.


