setGameScore

Set a user's score in a game. Works on a message carrier (chat_id + message_id) or an inline message carrier (inline_message_id).

Request

POST /:token/setGameScore

Parameters

Parameter	Type	Required	Description
user_id	Integer	Yes	Unique identifier of the target user
score	Integer	Yes	New score, must be a non-negative integer
force	Boolean	No	Whether the score may decrease. Defaults to false, in which case the new score must be strictly greater than the current one; set to true for corrections or anti-cheating
disable_edit_message	Boolean	No	Whether to skip auto-editing the game card to refresh the high score table. Defaults to false
chat_id	Integer	No	Required when inline_message_id is not specified: the chat that contains the game card
message_id	Integer	No	Required when inline_message_id is not specified: the message ID of the game card
inline_message_id	String	No	Required when chat_id and message_id are not specified: the inline message identifier

Provide either chat_id + message_id or inline_message_id.

Response

On success:

• For a regular message carrier, returns the edited Message object;
• For an inline message carrier, returns the Boolean value true.

{
  "ok": true,
  "result": {
    "message_id": 100,
    "chat": { "id": 987654321, "type": "private" },
    "date": 1700000000,
    "game": {
      "title": "Tower Blocks",
      "description": "Stack the blocks and chase the high score!",
      "photo": [{ "file_id": "AgACAgIAAx...", "width": 640, "height": 360 }],
      "text": "🏆 1. Alice — 980\n2. Bob — 760"
    }
  }
}

When force=false and the new score is not greater than the user's current score, the request is rejected.

Error Codes

Code	Description
400	Bad request parameters, e.g. the new score is not greater than the current one (with force=false), missing carrier parameters, or the game does not exist
401	Invalid or expired token
403	Bot does not have permission to set scores for this game
404	User, chat, or message does not exist
500	Internal server error

Examples

cURL (message carrier)

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 (inline carrier)

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