getAvailableGifts

Returns: GiftsOfficial docs ↗

Returns the list of gifts that can be sent by the bot to users and channel chats. Requires no parameters. Returns a Gifts object.

Returns

On success, the Gifts object is returned.

GramIO Usage

// List all available gifts with limited edition details
const { gifts } = await bot.api.getAvailableGifts();

console.log(`Total gifts available: ${gifts.length}`);

for (const gift of gifts) {
  const isLimited = gift.total_count !== undefined;
  const availability = isLimited
    ? ` (${gift.remaining_count}/${gift.total_count} left)`
    : " (unlimited)";
  console.log(`Gift ${gift.id}: ${gift.star_count} ⭐${availability}`);
}

// Find the cheapest available gift
const { gifts } = await bot.api.getAvailableGifts();

const cheapest = gifts.reduce((min, g) =>
  g.star_count < min.star_count ? g : min
);

console.log(`Cheapest: ${cheapest.id} — ${cheapest.star_count} ⭐`);

// Show a /gifts command listing only limited edition gifts
bot.command("gifts", async (ctx) => {
  const { gifts } = await bot.api.getAvailableGifts();
  const limited = gifts.filter((g) => g.total_count !== undefined);

  if (limited.length === 0) {
    return ctx.send("No limited gifts available right now.");
  }

  const lines = limited.map(
    (g) => `• ${g.star_count} ⭐ — ${g.remaining_count}/${g.total_count} left`
  );

  await ctx.send(`Limited gifts:\n${lines.join("\n")}`);
});

Errors

Code	Error	Cause
429	Too Many Requests: retry after N	Rate limit hit — check retry_after, use auto-retry plugin

TIP

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

Tips & Gotchas

• Returns the full Telegram gift catalog, not just affordable ones. Always check gift.star_count against your bot's own balance before calling sendGift — no validation error is thrown until the actual send fails.
• Limited gifts have total_count and remaining_count. A gift can sell out between the time you fetch the list and the time you send — handle the resulting error in sendGift gracefully.
• No parameters needed, no auth required. Any bot can call this endpoint — it's a public catalog lookup. Consider caching the result since the catalog changes infrequently.
• The sticker field gives a visual preview. Use gift.sticker.file_id to display the gift's sticker in your bot UI before the user confirms sending.
• Use remaining_count for UI indicators only. The count can change at any moment; don't use it to gate logic — always handle the send error as the source of truth.

See Also

• sendGift — send a gift from this catalog to a user or channel
• getUserGifts — get gifts received by a specific user
• getChatGifts — get gifts received by a channel
• getBusinessAccountGifts — get gifts owned by a managed business account
• Gift — the gift object type
• Gifts — the wrapper type returned by this method