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

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 data

If 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.

Phone, web page, server validation and session; a request that fails validation is rejected.
Read from left to right. The server checks the signature and data age before creating a session. The lower branch means rejection.

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.