### Games

Your bot can offer users HTML5 games to play solo or to compete against each other in groups and one-on-one chats. Create games via @BotFather using the /newgame command. Please note that this kind of power requires responsibility: you will need to accept the terms for each game that your bots will be offering.

- Games are a new type of content on Telegram, represented by the Game and InlineQueryResultGame objects.
- Once you've created a game via BotFather, you can send games to chats as regular messages using the sendGame method, or use inline mode with InlineQueryResultGame.
- If you send the game message without any buttons, it will automatically have a 'Play GameName' button. When this button is pressed, your bot gets a CallbackQuery with the game_short_name of the requested game. You provide the correct URL for this particular user and the app opens the game in the in-app browser.
- You can manually add multiple buttons to your game message. Please note that the first button in the first row must always launch the game, using the field callback_game in InlineKeyboardButton. You can add extra buttons according to taste: e.g., for a description of the rules, or to open the game's official community.
- To make your game more attractive, you can upload a GIF animation that demonstrates the game to the users via BotFather (see Lumberjack for example).
- A game message will also display high scores for the current chat. Use setGameScore to post high scores to the chat with the game, add the disable_edit_message parameter to disable automatic update of the message with the current scoreboard.
- Use getGameHighScores to get data for in-game high score tables.
- You can also add an extra sharing button for users to share their best score to different chats.
- For examples of what can be done using this new stuff, check the @gamebot and @gamee bots.

#### sendGame

Use this method to send a game. On success, the sent Message is returned.

Parameter | Type | Required | Description
--- | --- | --- | ---
business_connection_id | String | Optional | Unique identifier of the business connection on behalf of which the message will be sent
chat_id | Integer | Yes | Unique identifier for the target chat. Games can't be sent to channel direct messages chats and channel chats.
message_thread_id | Integer | Optional | Unique identifier for the target message thread (topic) of a forum; for forum supergroups and private chats of bots with forum topic mode enabled only
game_short_name | String | Yes | Short name of the game, serves as the unique identifier for the game. Set up your games via @BotFather.
disable_notification | Boolean | Optional | Sends the message silently. Users will receive a notification with no sound.
protect_content | Boolean | Optional | Protects the contents of the sent message from forwarding and saving
allow_paid_broadcast | Boolean | Optional | Pass True to allow up to 1000 messages per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot's balance
message_effect_id | String | Optional | Unique identifier of the message effect to be added to the message; for private chats only
reply_parameters | ReplyParameters | Optional | Description of the message to reply to
reply_markup | InlineKeyboardMarkup | Optional | A JSON-serialized object for an inline keyboard. If empty, one 'Play game_title' button will be shown. If not empty, the first button must launch the game.

#### Game

This object represents a game. Use BotFather to create and edit games, their short names will act as unique identifiers.

Field | Type | Description
--- | --- | ---
title | String | Title of the game
description | String | Description of the game
photo | Array of PhotoSize | Photo that will be displayed in the game message in chats.
text | String | Optional. Brief description of the game or high scores included in the game message. Can be automatically edited to include current high scores for the game when the bot calls setGameScore, or manually edited using editMessageText. 0-4096 characters.
text_entities | Array of MessageEntity | Optional. Special entities that appear in text, such as usernames, URLs, bot commands, etc.
animation | Animation | Optional. Animation that will be displayed in the game message in chats. Upload via BotFather

#### CallbackGame

A placeholder, currently holds no information. Use BotFather to set up your game.

#### setGameScore

Use this method to set the score of the specified user in a game message. On success, if the message is not an inline message, the Message is returned, otherwise True is returned. Returns an error, if the new score is not greater than the user's current score in the chat and force is False.

Parameter | Type | Required | Description
--- | --- | --- | ---
user_id | Integer | Yes | User identifier
score | Integer | Yes | New score, must be non-negative
force | Boolean | Optional | Pass True if the high score is allowed to decrease. This can be useful when fixing mistakes or banning cheaters
disable_edit_message | Boolean | Optional | Pass True if the game message should not be automatically edited to include the current scoreboard
chat_id | Integer | Optional | Required if inline_message_id is not specified. Unique identifier for the target chat
message_id | Integer | Optional | Required if inline_message_id is not specified. Identifier of the sent message
inline_message_id | String | Optional | Required if chat_id and message_id are not specified. Identifier of the inline message

#### getGameHighScores

Use this method to get data for high score tables. Will return the score of the specified user and several of their neighbors in a game. Returns an Array of GameHighScore objects.

> This method will currently return scores for the target user, plus two of their closest neighbors on each side. Will also return the top three users if the user and their neighbors are not among them. Please note that this behavior is subject to change.

Parameter | Type | Required | Description
--- | --- | --- | ---
user_id | Integer | Yes | Target user id
chat_id | Integer | Optional | Required if inline_message_id is not specified. Unique identifier for the target chat
message_id | Integer | Optional | Required if inline_message_id is not specified. Identifier of the sent message
inline_message_id | String | Optional | Required if chat_id and message_id are not specified. Identifier of the inline message

#### GameHighScore

This object represents one row of the high scores table for a game.

Field | Type | Description
--- | --- | ---
position | Integer | Position in high score table for the game
user | User | User
score | Integer | Score

And that's about all we've got for now.
If you've got any questions, please check out our Bot FAQ »