What is a Telegram mini game?
A web game that opens inside Telegram. Telegram calls these Mini Apps: JavaScript interfaces that launch inside Telegram and can fully replace a website. Players can open one from a bot profile, a button, the menu, inline mode, the attachment menu or a direct link.
Telegram added game features in November 2024. Mini apps can go full screen in portrait or landscape, read device motion, and be added as shortcuts to a phone home screen.
Telegram also has an older Gaming Platform. Bots can send HTML5 games as a message with a Play button. When a player sets a new high score, a service message goes to the chat.
Sources: Telegram Mini Apps documentation; Telegram Mini Apps 2.0 (17 November 2024); Telegram Gaming Platform documentation.
How many players can a Telegram game reach?
Telegram reports hundreds of millions of mini app users. On 6 June 2024, it said over 400 million users interact with bots and mini apps every month. On 30 June 2024, it said more than 500 million users interact with mini apps monthly. In July 2024, it said it had almost one billion monthly users.
These are platform totals, not the audience of one game. Discovery depends on your bot, your links and the chats where players share them.
Sources: Telegram blog (6 June 2024, 30 June 2024, 31 July 2024).
How do Telegram Stars payments work?
Digital goods in a bot or mini app must be sold for Stars. Telegram says all such transactions use the currency code XTR. It says this keeps mini apps within Apple and Google policies, and that it cannot show bots or mini apps to mobile users otherwise. Players buy Stars through in-app purchases.
The developer terms set the value. Each Star is worth an equivalent of 0.013 USD in rewards to the developer, or 0.02 USD in Telegram Ads credit. Stars may not be available for up to 21 days after you get them. Developers withdraw rewards through Fragment. Our arithmetic: 1,000 Stars equal about $13 in rewards.
Telegram said in June 2024 that it takes practically no commission from transactions in Stars, so only taxes and payment system fees apply. You can refund a payment with the refundStarPayment method.
| Item | Telegram value |
|---|---|
| Currency code for digital goods | XTR (Stars) |
| Reward value per Star | 0.013 USD equivalent |
| Ads credit per Star | 0.02 USD |
| Delay before use | Up to 21 days after receipt |
| Withdrawal | Through Fragment |
| Pre-checkout reply | Within 10 seconds |
Sources: Telegram Bot Payments API for Digital Goods and Services; Telegram Terms of Service for Bot Developers; Telegram blog (6 June 2024, 30 June 2024).
Why do Telegram games lose players so fast?
Many of the biggest ones grew on token rewards, not on play. Protos reported in November 2024 that Hamster Kombat, a tap-to-earn game, claimed 300 million players in August 2024. By November, its monthly player count was almost 41 million, a drop of about 86%, after its token fell in value.
This is one game in a crypto boom, reported by a news site. It still shows the risk: a link that spreads fast in chats can bring players who leave fast too. An indie game should judge Telegram on day 1 and day 7 return, not on launches.
Sources: Protos (4 November 2024).
What rules apply to player data in a mini app?
Telegram asks for a privacy policy and limits what you collect. Its developer terms say a bot or mini app must have a privacy policy that shows what data it stores, how, and why. They also say you may not collect or process data beyond what is essential for your service.
Telegram also says to validate the launch data, initData, on your server before you use it. You check its hash with an HMAC-SHA-256 signature, and you can check auth_date to refuse old data.
For storage, Telegram gives each bot CloudStorage of up to 1,024 items per user, and DeviceStorage of up to 5 MB per user.
- Collect only events you use: session start, level, purchase and share.
- Do not send the Telegram username or phone number to analytics.
- Use your own player ID, mapped on your server from the validated Telegram user ID.
- Name your analytics tool in your privacy policy.
Sources: Telegram Terms of Service for Bot Developers; Telegram Mini Apps documentation.
How do I track where Telegram players come from?
Use the startapp parameter in each link. Telegram direct links take the form t.me/botusername/appname?startapp=value. Telegram passes the value to the mini app in the start_param field and in the tgWebAppStartParam URL parameter.
A mini app is a web page on your own domain, so the Manalens web SDK works there as on your website. The SDK reads UTM, ref and ad click parameters, but not tgWebAppStartParam. So read start_param from Telegram and send it as a property of your first event. For a creator code, send a referral_code_redeemed event, and reports credit that creator.
- Give each post, chat or creator its own startapp value.
- On launch, send a mini_app_opened event with the start_param value.
- On your server, validate initData, then send identify with your own player ID.
- When a Stars payment succeeds, send a purchase event from your server with a numeric revenue property in USD.
- Compare D1 and D7 return and revenue by start_param after two weeks.
Sources: Telegram Mini Apps documentation; Manalens web SDK and referral codes documentation.
Which games fit Telegram?
Short, social web games that load fast on a phone. Telegram built its game features around chats: the Play button in a message, high score messages in the chat, a share button with the player's best score, and full-screen mode for more game genres. A game that players can finish a round of in a few minutes, and want to share with a group, uses all of these.
A long single-player game with big downloads fits less well. Players open a mini app from a chat, so a slow first load costs players before they see the game. Telegram says players can also collapse a mini app into a bar and come back later without a new load.
Our view: treat Telegram as a test channel first. Ship a small web slice, give it one startapp link per chat or creator, and keep the full game where it sells best.
- Rounds of a few minutes, with a score to beat.
- Touch controls that work in portrait or landscape.
- A small first download, so the game starts fast in a chat.
- A reason to share: a score, a challenge or a group mode.
- Items or a subscription that make sense to sell for Stars.
Sources: Telegram Gaming Platform documentation; Telegram Mini Apps 2.0 (17 November 2024); Telegram blog (30 June 2024).
How do I compare Telegram with my other channels?
Manalens is the analytics and growth engine built for games. The web SDK runs in your mini app as on any page of your domain. Send the startapp value as an event property and purchases as server events, then compare players, return rates and revenue from Telegram with your other channels in one attribution report.
Sources: Manalens product documentation.
Frequently asked questions
Do I need crypto to sell a game on Telegram?
Not to sell. Players buy Telegram Stars through in-app purchases from Apple or Google, then spend them in your mini app. Telegram says digital goods must be paid in Stars. Telegram said in June 2024 that developers can withdraw Stars as a Toncoin reward through Fragment. You can also spend Stars on Telegram Ads.
How much is a Telegram Star worth to a developer?
Telegram's developer terms say each Star gives an equivalent of 0.013 USD in rewards, or 0.02 USD in Telegram Ads credit. Telegram may change these values. Stars may not be available for up to 21 days after you get them. Our arithmetic: 10,000 Stars are about $130 in rewards.
Can I put an existing HTML5 game on Telegram?
Yes, as a mini app or through the Gaming Platform. A mini app is a web page that Telegram opens inside the app, and it can go full screen. Telegram says mini apps can also be added as home screen shortcuts on phones. Test touch controls, load time and file size on a phone before you share the link.
Is Telegram a good channel for a Steam game?
It is a different audience. Telegram mini games are short web games played inside a chat app, often on phones. A free web slice of your game can work there, but count it as its own channel. Measure day 1 return and purchases, and do not expect Telegram players to wishlist on Steam.
Sources and implementation
- Telegram: Telegram Mini Apps (read 18 November 2026) ↗
- Telegram: Mini Apps 2.0: Full-Screen Mode, Home Screen Icons, Geolocation and 10 more features (17 November 2024) ↗
- Telegram: Gaming Platform (read 18 November 2026) ↗
- Telegram: Bot Payments API for Digital Goods and Services (read 18 November 2026) ↗
- Telegram: Terms of Service for Bot Developers (read 18 November 2026) ↗
- Telegram: Telegram Stars: Pay for Digital Goods and More (6 June 2024) ↗
- Telegram: Mini App Bar, Paid Media, Story Search & More (30 June 2024) ↗
- Telegram: Telegram Browser, Gifting Stars and More (31 July 2024) ↗
- Protos: Hamster Kombat loses nearly 260 million players in just three months (4 November 2024) ↗