setGameScore

Returns: Message | TrueOfficial docs ↗

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.

Parameters

user_idIntegerRequired

User identifier

scoreIntegerRequired

New score, must be non-negative

forceBooleanOptional

Pass True if the high score is allowed to decrease. This can be useful when fixing mistakes or banning cheaters

disable_edit_messageBooleanOptional

Pass True if the game message should not be automatically edited to include the current scoreboard

chat_idIntegerOptional

Required if inline\message\id is not specified. Unique identifier for the target chat

message_idIntegerOptional

Required if inline\message\id is not specified. Identifier of the sent message

inline_message_idStringOptional

Required if chat\id and message\id are not specified. Identifier of the inline message

Returns

On success, Message | True is returned.

GramIO Usage

// Set a score in a regular game message (returns the updated Message)
const updatedMessage = await bot.api.setGameScore({
  user_id: 123456789,
  score: 1500,
  chat_id: -1001234567890,
  message_id: 42,
});

// Allow the score to decrease (e.g. fixing a bug or banning a cheater)
await bot.api.setGameScore({
  user_id: 123456789,
  score: 100,
  chat_id: -1001234567890,
  message_id: 42,
  force: true,
});

// Set score for an inline game message (returns True)
await bot.api.setGameScore({
  user_id: 123456789,
  score: 2000,
  inline_message_id: "AAAAAA...",
  disable_edit_message: true,
});

// Update score without auto-editing the game message UI
await bot.api.setGameScore({
  user_id: 123456789,
  score: 750,
  chat_id: -1001234567890,
  message_id: 42,
  disable_edit_message: true,
});

Errors

Code	Error	Cause
400	Bad Request: BOT_SCORE_NOT_MODIFIED	New score is not greater than current score and force is false — pass force: true to allow decreasing
400	Bad Request: message not found	message_id or inline_message_id does not exist or was deleted
400	Bad Request: chat not found	Invalid chat_id or bot was removed from the chat
400	Bad Request: score must be non-negative	Negative value passed as score — scores must be ≥ 0
400	Bad Request: message is not a game message	Target message does not contain a game — use a message sent via sendGame
403	Forbidden: bot was blocked by the user	User blocked the bot — catch and skip score updates for this user
429	Too Many Requests: retry after N	Rate limit hit — check retry_after

TIP

Use GramIO's auto-retry plugin to handle 429 errors automatically.

Tips & Gotchas

• Returns different types depending on message context. For regular (non-inline) game messages, the updated Message is returned so you can inspect it. For inline game messages, True is returned.
• force: true allows score decreases. By default Telegram rejects a score update that would lower the user's current score — this protects leaderboard integrity. Set force: true when correcting errors or removing cheaters.
• disable_edit_message: true separates score tracking from UI updates. Use this when you want to record a score server-side without immediately updating the scoreboard displayed in the chat. You can always call getGameHighScores to retrieve scores later.
• Either {chat_id, message_id} or inline_message_id is required, not both. Mixing the two will cause an error.
• Scores must be non-negative integers. Telegram does not support floating-point or negative scores.
• Game messages are created by sendGame. You cannot call setGameScore on arbitrary messages — the target must be a game message.

See Also

• getGameHighScores — retrieve the leaderboard for a game
• sendGame — send a game message that setGameScore can update
• Game — game object type
• GameHighScore — high score entry returned by getGameHighScores
• Message — return type for non-inline game messages