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 »