One Script Tag, One Server, One Currency: What Telegram Demands Before Your Licensed Games Run There
Before you license HTML5 games for a Telegram Mini App, know this: Telegram will not run a folder of builds. It wants a script tag, a server and Stars.
The pitch is easy to say out loud. Telegram has more users than almost anything else you could put a game inside, the games open without an install, and your catalogue is already web builds. Somebody in the room says "it's just HTML5, we already have a thousand of them", and the project gets a line in the quarter.
Then the build lands and nothing about it is "just HTML5". A Mini App is a bot with a webview attached, and Telegram's platform rules reach inside the page in three places that a licensed build is usually the worst possible shape for: the first script in the head, the server that validates who the player is, and the only currency you are allowed to charge in. None of those are hard problems on their own. All three become hard when the file you are shipping is one you licensed rather than one you wrote.
📦 The First Script in the Head Is Not Yours to Add
Telegram's own Mini Apps documentation is blunt about the entry point. You place the script telegram-web-app.js in the <head> tag before any other scripts, and that is what creates the window.Telegram.WebApp object every other platform feature hangs off — viewport, theme, back button, haptics, fullscreen, the lot.
Read that against how catalogue builds actually arrive. There are two common shapes and they fail differently.
A hosted URL. The licensor keeps the build on their infrastructure and you get a link to embed. You cannot edit that page's head. You cannot add the script. The Mini App you point at that URL loads a web page that has no idea it is inside Telegram: no theme colours, no back button, no way to close cleanly, no fullscreen, and no access to the player's identity.
A file drop. You receive the build and host it yourself. Now you can edit index.html — if the licence lets you. Modification rights are a real clause and plenty of catalogue agreements grant hosting and display without granting the right to alter the build. Inserting a third-party script into a delivered file is an alteration. It is a small one, and most licensors will say yes if asked, but "most licensors will say yes if asked" is a sentence that belongs in an email trail, not in your assumptions.
The wrapper works, and it costs you the API
The standard workaround is a wrapper page: you host a thin HTML shell that loads telegram-web-app.js in the head, then iframes the licensed game underneath. It works. It also puts the game two frames deep, which has consequences people discover late.
- The Telegram API lives in the wrapper, not in the game. Fullscreen, orientation lock and haptics are things your shell can call — but the game cannot ask for them, because the game does not know Telegram exists.
- Anything the game wants to trigger has to cross a frame boundary via
postMessage, which means the licensed build needs to already emit events you can listen for. Most do not. - The licensor's host has to permit framing at all. If their headers set
X-Frame-Optionsor aframe-ancestorspolicy that does not include your domain, the frame is blank and there is nothing you can do from your side.
None of this is fatal. It is just work, and it is work nobody scoped, done against builds you cannot patch.
🔐 The Bot Is the Backend, and initData Has to Be Checked Server-Side
Telegram hands your Mini App an initData payload describing the launching user. It is signed, and the documentation is explicit about the discipline: "You should only use data from initData on the bot's server and only after it has been validated", by comparing an HMAC-SHA-256 hash computed with your bot token. There is a separate Ed25519 path so third parties can verify without holding your token.
That single requirement rewrites the project plan. A licensed catalogue on a normal web portal is close to static: files on a CDN, a CMS in front, and the hosting bill is the cheapest line on the page. A Mini App is not static. You need a bot, a token, a running server that validates every launch, and a session store that maps Telegram user IDs to whatever progress or entitlement you are tracking. That is a backend with uptime obligations, and it is yours — not the licensor's.
One more constraint worth reading before you design the funnel: Mini Apps launched from direct links have no access to the chat. They cannot read messages or send anything on the user's behalf. If the growth plan in the deck involves the game posting a score to the player's group, check whether the launch surface you chose can actually do that.
👆 The Swipe That Closes Your Game
Telegram opens a Mini App partially. In its own words, the client "can display just the top part of the Mini App, with its lower part remaining outside the screen area" until the user drags it up or you call expand(). Since Bot API 8.0, Mini Apps can also go properly full-screen in both portrait and landscape via requestFullscreen(), and lock the device orientation with lockOrientation().
Use all of those. Then read the part everyone skips. You can disable vertical swipe gestures inside the app, but the documentation still warns that "the user will still be able to minimize and close the Mini App by swiping the Mini App's header". For a match-3 or a card game, fine. For anything with a vertical drag control — an endless runner, a slingshot, a drawing mechanic, a puzzle where you pull pieces down — that header strip is a live trapdoor sitting on top of your game's control scheme.
Which means the Telegram-suitable subset of a catalogue is not the whole catalogue. Titles that are horizontal-drag, tap-only or button-driven port cleanly. Titles built around vertical gestures need testing on a real handset before they go anywhere near a title list, and some of them will simply not survive.
⭐ Every Paid Thing Must Be Priced in Stars
If your Mini App sells anything digital, the rule is not negotiable. Telegram's payments documentation states that "payments for digital goods and services must be carried out exclusively in Telegram Stars", and spells out the enforcement: "Telegram cannot display your bot or mini-app to mobile users if you attempt to sell digital goods and services via other currencies or through third-party payment providers." The reason is upstream — Apple's and Google's rules about in-app purchases apply to Telegram's own apps, and Telegram passes the constraint down.
Three consequences for a licensed catalogue:
- Any IAP baked into a licensed build is dead weight. If a title ships with its own store screen wired to a payment SDK, it cannot run there as delivered. Either the licensor supplies a build with purchasing stripped, or you take the free-play version and put every paid mechanic in your own wrapper, priced in Stars.
- Your existing subscription rail does not transfer. Carrier billing, card-on-file, a portal wallet — none of them can take the money inside Telegram. You are running a second, parallel monetisation model for this channel.
- Disputes land on you. Refunds go through
refundStarPaymenton the Bot API, and Telegram is direct about where liability sits: "You as the bot owner have full responsibility in case any conflicts or disputes arise." Your licensor built the game. You are the merchant.
And if anyone in the room says the word "token": since January 2025, Telegram has made TON the exclusive blockchain for Mini Apps, with TON Connect as the only wallet-linking protocol, as reported by Cointelegraph. That is a whole separate compliance and treasury conversation, and it is not one to open by accident because a growth deck had the word "airdrop" in it.
📊 The Population Numbers Are Big and the Revenue Numbers Are Thin
The scale is real. Pavel Durov said in March 2025 that Telegram had passed one billion monthly active users. That is the number that gets the meeting.
The distribution underneath it is where the honesty has to come in, and the public data is weaker than the headline. A December 2025 analysis by GramBase, a Mini Apps analytics vendor, estimated roughly 55,000 active Mini Apps in 2026 against about 30,000 in 2025, with fewer than 2,000 of them generating more than $500 a month. The same piece labels its 2026 figures as annualised projections from Q1 data combined with the author's own tracking of payment flows — not audited platform numbers, and not something Telegram publishes. Treat the shape of it, not the decimal places: a very large ecosystem with a very short head, and a long tail earning close to nothing.
A Mini App is a cheap distribution experiment and an expensive revenue plan. Budget it as the former.
🧭 Three Buyers, Three Different Answers
The portal operator with an existing Telegram channel
Worth doing, and the only one of the three where the economics are obvious. You already have an audience inside the app, the Mini App is a second front door to games you already licensed, and the wrapper cost is amortised across every title you add later. Start with ten titles that pass the gesture test, not two hundred.
The brand running a four-week campaign
Usually the wrong container. You are standing up a bot, a validating backend and a Stars integration for something that will be switched off before the infrastructure has paid for itself — and the audience has to already be on Telegram, in your market, for it to reach anyone. A hosted campaign page with a licensed branded game in it does the same job with none of the platform surface. Choose Telegram here only if the audience genuinely lives there, which in parts of Eastern Europe, Central Asia, Iran and increasingly Southeast Asia is a defensible claim, and in most of Western Europe is not.
The operator or publisher with an Android catalogue already live
Do the APK maths first. If your reach problem is low-end Android devices in a market where installs are cheap and data is not, a Mini App and an Android game catalogue solve different halves of it, and the Mini App is the half you can ship in weeks rather than quarters. If your reach problem is store visibility, a Mini App does not touch it.
🚫 Five Ways a Telegram Games Launch Burns a Quarter
- Counting titles before testing gestures. The title count in the licence and the title count that survives the header-swipe problem are different numbers. Find the second one first.
- Assuming the licence covers it. "Web distribution" in a 2023 contract was not written with a messaging platform in mind. Named-platform scope is the clause to check, not territory.
- Shipping the ad-funded build. A licensed build carrying its own ad SDK inside a Mini App is at best a broken frame and at worst a policy problem. Ask for the clean build.
- Treating the bot as marketing's problem. The bot is production infrastructure with an uptime requirement. It needs an owner on the engineering rota, not a growth manager with a token in a spreadsheet.
- Modelling revenue off the headline user number. One billion MAU is the size of the room, not the size of your funnel. The distribution data says almost every Mini App earns very little.
📋 What to Settle With the Licensor Before You Build the Wrapper
Six questions, all answerable in one call, all cheaper to ask now:
- Does the licence permit distribution inside a third-party messaging platform, named explicitly?
- May we modify the delivered build's HTML to inject a platform script, or must we wrap?
- Will you supply builds hosted by us, or is hosting yours only? If yours, what is the framing policy on those pages?
- Can you supply builds with in-game purchasing and ad SDKs removed?
- Which titles in the catalogue use vertical drag as a primary control?
- If we ship there and Telegram changes a platform rule, who does the rework?
🎯 What You Get When You License HTML5 Games From a Direct Licensor
This is the practical argument for licensing direct rather than assembling a channel out of one-off asset purchases. A licence from a direct licensor is a conversation about scope: which titles, which platforms, which territories, which formats, and what you are allowed to do to the files once they arrive. Forestry Games has been licensing since 2017 and holds a catalogue of 1,049 titles spanning HTML5 and Android APK builds, with source available on applicable titles, branding options, and hosting either side of the line — self-hosted where you need control, hosted where you do not want the operational load. For a channel like this one, the modification and hosting terms matter more than the title count, and a catalogue that size means you can select the subset that actually fits the surface instead of forcing the whole thing through it. If you want to see what the selection looks like before you scope anything, license HTML5 games from the catalogue or browse the full catalogue and come back with a shortlist rather than a wish.
🧸 Licensing Branded Games for Campaigns, Portals and Messaging Apps
Where a channel needs recognisable characters rather than generic casual titles, branded content is licensable too. Forestry Games works with branded IP and has brand partnerships including Disney, Nickelodeon, Cartoon Network and Warner Bros, and businesses can license branded game content through it for campaigns, portals, events and apps. Branded titles carry tighter approval and compliance requirements than generic ones — which is exactly why the platform questions above should be settled before a character is attached, not after. Ask for a licence scope for the surface you have in mind, or request a portal and catalogue demo to see how the delivery works end to end.
✅ Do the Gesture Test This Week
The cheapest thing you can do next costs an afternoon. Take five titles you already licensed, put them behind a bare wrapper page with telegram-web-app.js in the head, open them on a real phone inside Telegram, and try to close the app by accident while playing. You will learn more from those five than from any amount of platform documentation, and you will find out immediately whether your builds are the shape this channel needs.
Then send the six licensing questions. If the answers come back clean — modification permitted, framing allowed, clean builds available, named platform in scope — the rest is ordinary engineering. If they do not, you have saved a quarter, and you know exactly which clause to renegotiate at renewal.
