The short answer
- 1Your server hosts the HTML5 game; Telegram supplies the game message, Play button and scores.
- 2Register with /newgame, send with sendGame, answer Play with your game URL.
- 3Post scores from your server with setGameScore, never from the page.
In this article
How a bot game is put together
A Telegram bot game is an HTML5 web game you build yourself, opened inside a chat. The game files live on your web server; Telegram provides the game message, the Play button and the high-score table.
| Who | Does what |
|---|---|
| @BotFather | Registers the game: a short name, description and photo, plus an optional animated preview |
| Your bot | Sends the game message, answers the Play button with the game's URL, records scores |
| Your web server | Serves the HTML5 game files |
| The Telegram app | Opens the game in its in-app browser and announces new high scores in the chat |
Building it, step by step
- In @BotFather, register the game with
/newgameand choose its short name. That name is how you refer to the game from now on. - Your bot calls
sendGamewith that short name, and a message with a game card and a Play button goes into the chat. Games can also be sent in inline mode; see building an inline bot. - When a user taps Play, your bot receives a button signal (
callback_query). Answer it withanswerCallbackQuery, putting your game's URL inurl, and the app opens that address. - When a game ends, your server records the score with
setGameScore. If the high score changes, the chat is notified and the table in the game message updates. Read the rankings withgetGameHighScores.
For request basics and the token, see your first Bot API requests; for answering button signals, see bot buttons.
Scores come from your server
Rules to follow
- If you add more buttons to the game message, the first button in the first row must be the one that launches the game.
- Telegram may append its own parameters, with names starting with
tg, to your game URL. Name your own URL parameters so they do not clash. - A share button lets players spread the game to other chats, and the official JavaScript lets a game share a score from inside the game.
A game or a mini app?
| What you need | Better fit |
|---|---|
| A score table and high-score announcements inside the chat are the point | Bot game |
| Full-screen use, payments, login, saved data and other app features | Mini app; see opening a mini app from the menu button and verifying mini app users |
How players decide whether to trust a game link is covered in how Telegram games work and what to trust.
FAQ
How do I make a game for a Telegram bot?
Host an HTML5 game, register it with /newgame in @BotFather, send it with sendGame and answer the Play button with your game's URL.
How are game scores saved?
Your server calls setGameScore; the chat's score table updates when a high score changes.
Should I build a bot game or a mini app?
A bot game if the in-chat score table is the point; a mini app for full-screen use, payments or logins.
Sources
At a glance
- 1Register
/newgame in @BotFather; the short name identifies the game.
- 2Launch
answerCallbackQuery with url opens your game.
- 3Scores
setGameScore from the server; read with getGameHighScores.
Updated
