Telegram mini games: what they are, how players find them, and how to build one

Telegram mini games are HTML5 games that run inside the Telegram app. Technically, they are usually Telegram Mini Apps: web apps built with HTML, CSS and JavaScript that Telegram opens in its own full-featured view, already knowing who the player is. Telegram describes Mini Apps as interfaces built with JavaScript that "can be launched right inside Telegram" and "can completely replace any website" (Telegram Mini Apps docs). No store download, no sign-up form, no separate login.

Below: the two technical routes, how players launch a game, examples, a build plan and costs. If you already know you want a game built for your brand, our Telegram Mini App game development page has the scope and fixed starting price.

Methodology: every platform fact below comes from Telegram's official documentation, terms and blog, or from engine documentation, checked on October 31, 2026. Our own prices come from our pricing page.

Mini Apps vs the Bot Gaming Platform

Telegram has two official ways to put a game in front of players. The Gaming Platform came first: bots "can offer their users HTML5 games to play solo or to compete against each other in groups and one-on-one chats" (Telegram Gaming Platform). You register a game with the /newgame command in @BotFather, the bot sends a game message with a Play button, and Telegram opens your URL in its in-app browser. Mini Apps are the newer, much broader platform, and Telegram has kept adding game-friendly features to them.

Our view: the Gaming Platform is fine for a quick group-chat game. For anything a brand will promote or monetize, build a Mini App.

How players find and launch Telegram mini games

In our view, distribution is the platform's real advantage. Telegram's docs list these entry points (Telegram Mini Apps docs):

• Menu button. Chats with bots show a menu button that can launch the Mini App.
• Keyboard and inline buttons. A bot message can carry a web_app button that opens the game.
• Direct links. A link in the form https://t.me/botusername/appname?startapp=command opens the Mini App in the current chat. The start parameter is how you track campaigns and referrals.
• Main Mini App. A bot that is a Mini App can show a prominent Launch app button on its profile, also reachable with https://t.me/botusername?startapp. Bots that enable a main Mini App are shown in the Apps tab of search, and ones that also accept Stars payments may be featured in the Telegram Mini App Store.
• Inline mode. Mini Apps can be opened from inline mode in any chat.
• Home-screen shortcuts. Since Bot API 8.0, addToHomeScreen lets players put a shortcut to your game on their phone's home screen.
• Attachment menu. Telegram says this integration "is currently only available for major advertisers on the Telegram Ad Platform", so do not plan a launch around it.

Telegram's Mini Apps 2.0 update on November 17, 2024 added the main game-focused tools: Mini Apps can "use the entire screen in portrait or landscape orientation", read device motion "to add unique controls", share location for location-based games and send Stars gifts "as rewards to celebrate achievements" (Telegram blog).

Notable examples, and why brands skip tap-to-earn

Telegram's own Mini Apps 2.0 announcement pointed to @playdeckbot, @tverse and @major, mentioning "the Major Maze game on the Games tab", as apps using the new features (Telegram blog).

The format became widely known through the tap-to-earn wave of 2024, led by clickers such as Hamster Kombat that promised players a crypto token in return for in-game activity. That model ties the game to token prices and payouts the brand does not control.

That history is one reason we steer brand games for loyalty, launches or lead capture away from tokens. A brand game is measured differently: time spent with the brand, opted-in leads and visits to the product, with real offers as prizes. The rules point the same way. Telegram's developer terms require that Mini Apps with cryptocurrency functionality are "based exclusively on The Open Network (TON) blockchain" and that wallet features connect only through the TON Connect SDK, while digital goods must be sold in Stars (Telegram Bot Platform Developer Terms). A game without crypto avoids that whole layer.

How to build a Telegram mini game, step by step

1. Design the loop for the phone. Sessions are short. Telegram's design guidelines ask for a mobile-first, responsive layout and animations that are "smooth, ideally 60fps" (Telegram design guidelines), and suggest reducing effects on low-performance devices. Respect the safe-area and content-safe-area insets so the game doesn't sit under Telegram's own controls.
2. Create the bot and the Mini App in @BotFather. Create a bot, host your game at an HTTPS URL, then set it as the bot's Main Mini App under /mybots > Select Bot > Bot Settings > Configure Mini App > Enable Mini App. BotFather also lets you customize the loading screen with your icon and colors for light and dark themes.
3. Pick an engine (comparison in the next section) and keep the first load light.
4. Add Telegram's JavaScript SDK. Include <script src="https://telegram.org/js/telegram-web-app.js"></script> and use window.Telegram.WebApp for theme colors, full screen, storage and sharing.
5. Validate the player on your server. Send Telegram.WebApp.initData to your backend with every session. Telegram warns that initDataUnsafe "should not be trusted"; use the signed initData only after validation (details below).
6. Build leaderboards and sharing on top of that identity. Store scores keyed by the validated Telegram user id, run sanity checks and rate limits before a score is accepted, and use shareMessage or a startapp link to bring friends in.
7. Add Stars payments if you sell anything digital (see payments).
8. Test on real phones, then launch with tracked links per channel and analytics on sessions and drop-off.

Validating initData on the server

Telegram's rule is short: build a data-check-string from every received field except hash, "sorted alphabetically, in the format key=<value>", joined with line feeds. Keep the signature field in the string; only hash is removed. The secret key is the HMAC-SHA-256 of your bot token with the constant string WebAppData as the key, and the hash must equal the hex HMAC-SHA-256 of the data-check-string with that secret. Also check auth_date so old launch data can't be replayed. In Node.js:

import crypto from "node:crypto";

export function validateInitData(initData, botToken, maxAgeSec = 3600) {
  const params = new URLSearchParams(initData);
  const hash = params.get("hash");
  params.delete("hash");
  const dataCheckString = [...params.entries()]
    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
    .map(([k, v]) => `${k}=${v}`)
    .join("\n");
  const secret = crypto.createHmac("sha256", "WebAppData").update(botToken).digest();
  const expected = crypto.createHmac("sha256", secret).update(dataCheckString).digest("hex");
  const got = Buffer.from(hash || "", "hex"), exp = Buffer.from(expected, "hex");
  if (got.length !== exp.length || !crypto.timingSafeEqual(got, exp)) return null;
  const age = Date.now() / 1000 - Number(params.get("auth_date"));
  if (!(age < maxAgeSec)) return null;           // too old: ask the client to relaunch
  return JSON.parse(params.get("user") || "null"); // trusted Telegram user
}

If a third party needs to verify the data without your bot token, Telegram also signs initData with an Ed25519 signature that can be checked against Telegram's public key (Telegram Mini Apps docs).

Choosing an engine: Phaser, PixiJS, Godot or Unity

A Mini App is a web page, so any engine with a web export can work. Load size and performance on mid-range phones decide the choice.

Godot's web export docs say the .wasm file compresses to about a quarter of its original size with gzip, so serve compressed files. And Godot recommends single-threaded web exports, which avoids the cross-origin isolation headers that threaded builds require (Godot docs). We use Godot for our own games, but for most brand games a light 2D HTML5 build opens fastest on mobile data.

Payments: Telegram Stars for digital goods

Telegram's payment docs are unambiguous: "all sales of digital goods and services are carried out exclusively in Telegram Stars", currency code XTR (Telegram Stars payments). That covers extra lives, skins and premium levels. The flow:

1. Create an invoice in XTR with an empty provider_token.
2. When the player confirms, your bot receives a pre_checkout_query and must answer it within 10 seconds.
3. Grant the item only after the successful_payment update reaches your server.
4. Handle refunds with refundStarPayment, and respond to the /paysupport and /terms commands. Telegram makes the developer responsible for payment disputes.

Mini Apps can also sell subscriptions in Stars. On the developer side, Telegram's terms say developers "can receive an equivalent of 0.013 USD worth of rewards for each Telegram Star", processed through Fragment, and that Stars may take up to 21 days to become available (Telegram Developer Terms). Physical goods follow different rules.

Cost and timeline

The price follows the scope: game modes, custom art, the leaderboard and anti-cheat backend, Stars payments, analytics and live-ops tools. Our published starting prices:

Larger scopes are quoted at a fixed price. On timing: a focused single-mode MVP is a matter of weeks, not months, and we give a dated plan with the quote. Full details are on our Telegram game development service page; for native apps, see how much it costs to build an app in 2026.

FAQ

Are Telegram mini games free to play?

Opening a Mini App costs players nothing: there is no store download, and the game runs inside Telegram. Developers can sell digital items or subscriptions, and Telegram's rules say those sales must be paid in Telegram Stars.

Do Telegram mini games need crypto?

No. A Mini App is a web app, and crypto is optional. Telegram's developer terms say that Mini Apps which do implement cryptocurrency functionality must be based exclusively on the TON blockchain and connect wallets only through the TON Connect SDK.

Should I use the Bot Gaming Platform or a Mini App?

For a new game, usually a Mini App. The older Gaming Platform still works and gives you built-in per-chat high scores, but Mini Apps add launch points such as the menu button, direct links and the Launch app button, plus full-screen mode, home-screen shortcuts, device storage, sharing and Stars subscriptions.

How long does it take to build a Telegram mini game?

It depends on the game. A focused single-mode game with leaderboards is a matter of weeks, not months; more modes, a Stars shop and live-ops tools add time. We give a dated plan together with a fixed quote.

Sources

1. Telegram: Mini Apps on Telegram (Bot API docs, through Bot API 10.1), checked October 31, 2026
2. Telegram: Gaming Platform
3. Telegram: Bot Payments for Digital Goods and Services (Telegram Stars)
4. Telegram: Bot Platform Developer Terms
5. Telegram blog: Mini App 2.0 update (November 17, 2024)
6. Godot Engine docs: Exporting for the Web
7. Unity docs: Web browser compatibility
8. Phaser on GitHub
9. PixiJS

VLWritten by the VL Studio team. We build games, apps, websites and automations for businesses and founders in the US and Europe.