Telegram Games: An Intermediate Guide
Tags: telegram, bot, telegrambot, game
Published: 2022-08-01 06:07:57

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](https://core.telegram.org/bots/games).

![Telegram Gaming Platform documentation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/u4830opk886flalnvvbw.png)

While reading it, I felt it was rather skimpy on the details. I also wished they would link to the [bot API documentation](https://core.telegram.org/bots/api) 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](https://t.me/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](https://core.telegram.org/bots/inline) and [callback buttons](https://core.telegram.org/bots/2-0-intro#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.

![User sends /start, bot responds with game](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3ljpajcpe3o5maj7k24a.png)

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

![Sequence diagram for sending games to chats as regular messages](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ogumg4cgn7ze3uulrdkv.png)

1. The user initiates the conversation with your chosen phrase
2. Your bot will receive a [Message](https://core.telegram.org/bots/api#message) object containing the message that was sent
3. You may respond using the [`sendGame`](https://core.telegram.org/bots/api#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`](https://core.telegram.org/bots/api#callbackquery) with `game_short_name` to your bot
3. Your bot calls [`answerCallbackQuery`](https://core.telegram.org/bots/api#callbackquery) 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.

![Sequence diagram for offering games via inline mode](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0rziogzx1l9ocvvzyo91.png)

1. The user initiates the interaction by typing "_@your_bot_username_" in any chat
2. Telegram sends an [`InlineQuery`](https://core.telegram.org/bots/api#inlinequery) to your bot
3. Your bot calls [`answerInlineQuery`](https://core.telegram.org/bots/api#answerinlinequery) with an array of [`InlineQueryResultGame`](https://core.telegram.org/bots/api#inlinequeryresultgame)
4. Telegram displays the results to the user ![Telegram displays the results to the user](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/dm08s3brau5e1pl36l3o.png)
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. ![User sends a message with the game](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4vhef4j62vz82a6gsviy.png)

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!