How Games Work in Telegram: Games API vs Mini App Games
Basics4 minInnovialabs editorial team
In short
The Games API is a simple legacy way to run an HTML5 game with an in-chat high score table, while a Mini App adds full screen, verified user data, Stars payments and sharing; new projects almost always choose a Mini App.
The short answer: two ways to build a game in Telegram
Telegram has two mechanisms for games, and both run an ordinary HTML5 game inside the app.
- Games API — the platform that predates Mini Apps. A bot sends a game card with a "Play" button to a chat, the game opens in the built-in browser, and scores go into a shared high score table.
- Mini App — a web app inside Telegram with access to user data, full-screen mode, Stars payments and sharing features. A game here is just one kind of Mini App.
For a new project, a Mini App is the usual choice. The Games API makes sense for simple games where an in-chat leaderboard for a group is the main point.
How the Games API works
- In BotFather,
/newgamecreates a game: title, description, image and a short name. - The bot calls
sendGamewith that short name. A card with a launch button appears in the chat. - When tapped, the bot receives a
callback_querywithgame_short_nameand replies withanswerCallbackQuerycontaining the game URL. - The game opens; when it ends, your server calls
setGameScore, andgetGameHighScoresreturns the ranking for that chat. - Through inline mode, a user can post the game to any chat and challenge friends.
The limitation: Telegram passes almost nothing to the game page. You identify the player yourself — for example, with a signed parameter in the URL that the bot generates.
How a Mini App game works
A Mini App receives initData with a signature that your server uses to verify the user. On top of that you get things the Games API lacks:
- full-screen mode and screen orientation control;
- Stars payments right inside the game;
- cloud storage for small amounts of player data;
- haptics, Telegram interface buttons, a home screen shortcut;
- sharing: prepared messages to send to chats, posting to stories, links with a parameter for referral mechanics.
Comparison
| Criterion | Games API | Mini App |
|---|---|---|
| Launch | Game card in a chat | Menu button, link, message button |
| User data | You pass it via the URL | Signed initData |
| High scores | Built in, per chat | You build them on your server |
| Payments | Only separately through the bot | Stars inside the game |
| Screen | Built-in browser | Including full-screen mode |
| Platform development | No notable changes | Actively evolving |
Monetization
- Stars. For digital goods and services inside a Mini App, Telegram requires Stars. Think extra lives, skins, levels, an ad-free mode.
- Ads. Third-party ad networks exist for Mini Apps: banners, interstitials, rewarded video. Make sure ads do not break the game loop.
- Beyond revenue. For a brand, a game usually pays off not through in-game sales but through channel subscribers, leads, promo codes and awareness.
Viral mechanics
- Referral links. A link with a
startappparameter shows who invited the player; the inviter gets a bonus. - Challenge a friend. The player sends their result to a chat as a ready-made message with a "Play" button.
- Rankings among friends and in groups are a strong reason to come back.
- Stories. Posting a result to a story brings new players from contacts.
Keep these mechanics from turning into spam: neither Telegram's rules nor users tolerate it.
What a business can realistically build
- A promo game for a product launch or seasonal campaign, with promo codes as prizes.
- A quiz about the product or brand with a result people want to share.
- A gamified loyalty program: points for purchases, levels, daily tasks.
- Game-like onboarding for a complex product.
If the game gives away prizes, check your country's legal requirements for promotional campaigns and lotteries in advance.