Telegram Games: An Intermediate Guide

I recently created a game on Telegram. This was not my first Telegram bot, but it would be my first game. Hence, I first checked the official Telegram documentation for their gaming platform.

While reading it, I felt it was rather skimpy on the details. I also wished they would link to the bot API documentation directly, so that I could see the exact objects, methods and fields involved.

This guide is meant to provide slightly more details (and useful links) than the existing documentation, but is not meant to be a step-by-step guide. It is language-agnostic so that you can apply these concepts regardless of which language you choose to write your bot and game in.

Creating a Game

1. Create a Telegram Bot using /newbot on @BotFather
2. Enable inline mode for the bot using /setinline
3. Create a new game using /newgame

After this process, you will have your bot token and your game_short_name, which will be used later.

Launching the Game

Here's what the documentation says:

Once the game is created, your bot can send it to chats as regular messages, or offer them via inline mode.

Let's break that down.

It may help to read about inline mode and callback buttons first.

Sending games to chats as regular messages

For example, you could have the bot respond to the /start command (or any other command/phrase of your choice) by sending the game.

Here's a sequence diagram for what goes on behind the scenes.

1. The user initiates the conversation with your chosen phrase
2. Your bot will receive a Message object containing the message that was sent
3. You may respond using the sendGame API, which is fairly straightforward as the only required fields are chat_id and game_short_name (from the set up process)
4. The bot sends a message with the game and a "Play Game Name" callback button

Next, the callback interactions occur.

1. The user clicks on "Play Game Name"
2. Telegram sends a CallbackQuery with game_short_name to your bot
3. Your bot calls answerCallbackQuery with a url to the game
4. Telegram opens the url to the game

Offering games via inline mode

This was the part that confused me the most.

Here is the equivalent sequence diagram for the interactions between the user, Telegram and your bot.

1. The user initiates the interaction by typing "@your_bot_username" in any chat
2. Telegram sends an InlineQuery to your bot
3. Your bot calls answerInlineQuery with an array of InlineQueryResultGame
4. Telegram displays the results to the user
5. The user selects a game from the list
6. The user sends a message (via your bot) the game and a "Play Game Name" callback button.

The remaining flow for launching the game via callback interactions is the same as before.

Conclusion

This guide provides more elaboration on the interactions between the user, Telegram and your bot when launching a game.

An interesting difference between these two methods is that in the first, the bot is the one who sends the message containing the game. In the second, the user who initiated the inline query is the one who sends the game. This is because the bot may not be a part of the group chat (as it is an inline interaction).

Hope this guide helped you, and happy coding!