getUserChatBoosts

Returns: UserChatBoostsOfficial docs ↗

Use this method to get the list of boosts added to a chat by a user. Requires administrator rights in the chat. Returns a UserChatBoosts object.

Parameters

chat_idIntegerStringRequired

Unique identifier for the chat or username of the channel (in the format @channelusername)

user_idIntegerRequired

Unique identifier of the target user

Returns

On success, the UserChatBoosts object is returned.

GramIO Usage

// Get all boosts a user has added to a channel:
const result = await bot.api.getUserChatBoosts({
  chat_id: "@mychannel",
  user_id: 12345678,
});

console.log(`User has ${result.boosts.length} active boosts`);

// Gate a feature behind at least one channel boost:
bot.command("exclusive", async (ctx) => {
  if (!ctx.from) return;

  const result = await bot.api.getUserChatBoosts({
    chat_id: ctx.chat.id,
    user_id: ctx.from.id,
  });

  if (result.boosts.length === 0) {
    return ctx.send("Boost our channel to unlock this feature!");
  }

  await ctx.send(`Welcome, booster! You have ${result.boosts.length} active boost(s).`);
});

// Require a minimum number of boosts for premium access:
bot.command("premium", async (ctx) => {
  if (!ctx.from) return;

  const result = await bot.api.getUserChatBoosts({
    chat_id: ctx.chat.id,
    user_id: ctx.from.id,
  });

  const boostCount = result.boosts.length;
  const required = 3;

  if (boostCount < required) {
    return ctx.send(`You need ${required - boostCount} more boost(s) to access premium content.`);
  }

  await ctx.send("Premium access granted!");
});

Errors

Code	Error	Cause
400	Bad Request: chat not found	Invalid or inaccessible chat_id — verify the bot is a member of the chat
400	Bad Request: user not found	The user_id doesn't correspond to a known user
400	Bad Request: not enough rights	Bot is not an administrator in the specified chat
403	Forbidden: bot is not a member of the channel chat	Bot was removed from the channel

Tips & Gotchas

• Bot must be an administrator. The bot needs admin rights in the target chat — this method fails with a 400 error for non-admin bots.
• Works for channels and supergroups. You can pass either a numeric chat_id or a @username for public channels. For supergroups, use the numeric ID.
• Empty boosts array means no active boosts. The method succeeds even if the user has never boosted — check result.boosts.length === 0 rather than expecting an error.
• Boost source inspection. Each ChatBoost in result.boosts includes an expiration_date and a source field (ChatBoostSource) indicating whether it came from Telegram Premium, a giveaway, or a gift code.
• No caching. Boosts can expire at any time — always fetch fresh data when making access decisions rather than caching the result.

See Also

• UserChatBoosts — return type with the boosts array
• ChatBoost — individual boost entry structure
• ChatBoostSource — union type for boost origin (Premium, giveaway, gift code)
• getMe — confirm the bot identity before admin checks