setGameScore

设置用户在游戏中的分数。可作用于消息载体（chat_id + message_id）或内联消息载体（inline_message_id）。

请求

POST /:token/setGameScore

参数

参数	类型	必填	描述
user_id	Integer	是	目标用户的唯一标识符
score	Integer	是	新的分数，必须为非负整数
force	Boolean	否	是否允许分数下降。默认 false，此时新分数必须严格大于现有分数；用于纠错或反作弊时可设为 true
disable_edit_message	Boolean	否	是否不自动编辑游戏卡片以刷新高分榜，默认 false
chat_id	Integer	否	当未指定 inline_message_id 时必填：游戏卡片所在聊天
message_id	Integer	否	当未指定 inline_message_id 时必填：游戏卡片的消息 ID
inline_message_id	String	否	当未指定 chat_id 和 message_id 时必填：内联消息标识符

chat_id + message_id 与 inline_message_id 两组参数二选一。

响应

成功时：

• 若为普通消息载体，返回编辑后的 Message 对象；
• 若为内联消息载体，返回 Boolean 值 true。

{
  "ok": true,
  "result": {
    "message_id": 100,
    "chat": { "id": 987654321, "type": "private" },
    "date": 1700000000,
    "game": {
      "title": "Tower Blocks",
      "description": "堆叠方块，挑战最高分！",
      "photo": [{ "file_id": "AgACAgIAAx...", "width": 640, "height": 360 }],
      "text": "🏆 1. Alice — 980\n2. Bob — 760"
    }
  }
}

当 force=false 且新分数不大于该用户现有分数时，请求会被拒绝。

错误码

错误码	描述
400	请求参数错误，如新分数不大于现有分数（且 force=false）、载体参数缺失或游戏不存在
401	Token 无效或已过期
403	Bot 无权设置该游戏的分数
404	用户、聊天或消息不存在
500	服务器内部错误

示例

cURL（消息载体）

curl -X POST "https://api.safew.bot/<token>/setGameScore" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 111222333,
    "score": 980,
    "chat_id": 987654321,
    "message_id": 100
  }'

cURL（内联载体）

curl -X POST "https://api.safew.bot/<token>/setGameScore" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 111222333,
    "score": 980,
    "inline_message_id": "AAQAAxkBAAI..."
  }'