Telegram Bot不仅能发送文本、图片和文件，还能创建可交互的自定义HTML5游戏。这种游戏机制让开发者能够构建从休闲小游戏到复杂排行榜的互动体验，同时借助Telegram的社交属性快速传播。本文将从零开始，介绍如何通过Bot API创建游戏消息、处理玩家点击、更新得分，帮助您快速掌握自定义游戏的开发入门。
什么是Telegram自定义游戏？
Telegram的自定义游戏是一种特殊类型的消息，它包含一个游戏短名（game_short_name），用户点击消息内的“Play”按钮后，会以全屏模式打开一个HTML5游戏页面。游戏托管在您的服务器上，通过JavaScript与Telegram Web App交互，并将得分数据回传至Bot。
Telegram负责游戏入口和分数展示，而游戏逻辑由开发者完全控制。您可以通过Bot API发送游戏消息，通过回调查询（CallbackQuery）感知用户点击，并通过setGameScore接口更新用户成绩。
第一步：在BotFather中创建游戏
在使用API发送游戏前，必须先在Telegram官方机器人@BotFather处注册游戏，获得一个唯一的游戏短名。具体步骤如下：
- 向@BotFather发送
/newgame命令； - 选择您已经创建的Bot，或创建一个新的Bot；
- 按照提示输入游戏的短名（例如
mygame）、标题、描述以及一张封面图片； - 设置游戏动画（可选）与游戏URL，该URL指向您的HTML5游戏页面。
完成后，BotFather会返回确认信息，记下您设置的游戏短名，例如 mygame，后续API调用中会用到。
第二步：发送游戏消息（sendGame）
使用sendGameAPI可以发送游戏消息。该接口最少需要提供chat_id（接收消息的聊天ID）和game_short_name（游戏短名）。您还可以附加一个内联键盘，作为“Play”按钮的包装。
以下是一个使用Python python-telegram-bot库发送游戏消息的示例：
from telegram import Bot, InlineKeyboardButton, InlineKeyboardMarkup
bot = Bot(token="YOUR_BOT_TOKEN")
# 创建内联键盘，按钮文字为“Play”，回调数据为任意标识
keyboard = [[InlineKeyboardButton("Play", callback_data="play_game")]]
reply_markup = InlineKeyboardMarkup(keyboard)
# 发送游戏消息
bot.send_game(
chat_id=123456789,
game_short_name="mygame",
reply_markup=reply_markup
)如果您希望用户在点击“Play”后直接打开游戏，而不显示键盘，也可以省略reply_markup，这时默认按钮会显示游戏缩略图。
第三步：处理游戏回调查询
当用户点击游戏消息中的按钮时，Telegram会向Bot发送一个CallbackQuery更新。您需要处理这个回调，先调用answer_callback_query应答，然后可以进一步操作，如更新得分。
在python-telegram-bot中，通过回调处理器捕获：
from telegram.ext import CallbackQueryHandler, Updater
def game_callback(update, context):
query = update.callback_query
user = query.from_user
# 应答回调，可附带提示文字
query.answer(text="游戏已启动！")
# 这里可以触发您的游戏逻辑，例如发送游戏URL或记录状态
# 在游戏结束后，通过set_game_score更新得分（见下一步）
# 注册回调处理器
def main():
updater = Updater("YOUR_BOT_TOKEN")
updater.dispatcher.add_handler(CallbackQueryHandler(game_callback))
updater.start_polling()
updater.idle()注意：回调数据中的game_short_name可以通过query.game_short_name获取（如果存在），方便您确认用户点击的是哪个游戏。
第四步：更新玩家得分（setGameScore）
当用户完成游戏后，您的游戏页面应把得分发送给Bot服务器。Bot可以通过setGameScoreAPI将得分写入Telegram。该接口要求提供user_id和score，并且需要指定一个游戏消息（通过chat_id + message_id，或直接使用inline_message_id）。
在python-telegram-bot中调用：
# 假设用户完成了游戏，我们将其得分设为500
bot.set_game_score(
user_id=user.id,
score=500,
chat_id=query.message.chat.id,
message_id=query.message.message_id,
force=True # 允许分数被覆盖
)设置得分后，Telegram会自动更新游戏消息中的分数，并将结果反馈给用户。您可以使用getGameHighScores获取排行榜，方便展示最高分。
进阶：使用内联模式与排行榜
除了在群组或私聊中发送游戏，您还可以通过内联模式（Inline Mode）让用户在任意聊天中输入@YourBot 游戏名来调用游戏。另外，getGameHighScoresAPI可以返回特定用户或所有用户的最高分，用于实现排行榜功能。
下面是一个使用getGameHighScores获取用户前10名的示例：
high_scores = bot.get_game_high_scores(
user_id=user.id,
chat_id=chat_id,
message_id=message_id
)
for item in high_scores:
print(item.player.first_name, item.score)注意事项与调试技巧
- 确保游戏域名使用HTTPS，并正确设置Telegram Web App支持，否则游戏无法加载。
- 如果发送游戏时出现
Bad Request: game_short_name not found，请检查是否已在BotFather中注册且名称拼写无误。 - 回调查询的
answer必须在几秒内完成，否则会超时提示用户。 - 在生产环境中，建议使用Webhook代替长轮询，以提高响应速度和稳定性。
总结
本文介绍了Telegram Bot自定义游戏的完整入门流程：从BotFather创建游戏、通过sendGame发送消息、处理回调、设置得分，到使用排行榜功能。这一功能为开发者提供了结合网页技术与即时通讯的强大互动能力。掌握这些API后，您可以进一步探索游戏内支付、多人对战等高级特性，为用户带来更丰富的体验。