setStickerKeywords

Returns: TrueOfficial docs ↗

Use this method to change search keywords assigned to a regular or custom emoji sticker. The sticker must belong to a sticker set created by the bot. Returns True on success.

Parameters

stickerStringRequired

File identifier of the sticker

keywordsString[]Optional

A JSON-serialized list of 0-20 search keywords for the sticker with total length of up to 64 characters

Returns

On success, True is returned.

GramIO Usage

// Add search keywords to a sticker
await bot.api.setStickerKeywords({
  sticker: "CAACAgIAAxkBAAIBcWZ...",
  keywords: ["happy", "smile", "funny", "laugh"],
});

// Remove all keywords from a sticker (pass empty array or omit)
await bot.api.setStickerKeywords({
  sticker: "CAACAgIAAxkBAAIBcWZ...",
  keywords: [],
});

// Omitting keywords also clears them
await bot.api.setStickerKeywords({
  sticker: "CAACAgIAAxkBAAIBcWZ...",
});

// Update keywords for every sticker in a set
const set = await bot.api.getStickerSet({ name: "my_pack_by_mybot" });

const keywordMap: Record<string, string[]> = {
  happy: ["happy", "smile", "joy"],
  sad: ["sad", "cry", "upset"],
};

for (const sticker of set.stickers) {
  const emoji = sticker.emoji ?? "";
  const keywords = keywordMap[emoji] ?? [];
  await bot.api.setStickerKeywords({
    sticker: sticker.file_id,
    keywords,
  });
}

Errors

Code	Error	Cause
400	Bad Request: STICKER_ID_INVALID	The sticker file_id is invalid or the sticker doesn't belong to a set created by this bot
400	Bad Request: keywords list is too long	More than 20 keywords provided — trim the list
400	Bad Request: total keywords length is too long	Sum of all keyword string lengths exceeds 64 characters — use shorter keywords
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

• Total character budget is 64, not per-keyword. All keywords combined (including any separators) must fit within 64 characters. With 20 keywords that's an average of 3 characters each — keep keywords short.
• Keywords improve discoverability in inline mode. When users search for stickers in the inline sticker picker by typing words, keywords are matched. Good keywords significantly improve how often your stickers appear.
• keywords is optional — omitting clears all keywords. Passing keywords: [] or omitting the field entirely removes all keywords from the sticker. This is intentional — useful for resetting.
• Only works on bot-created sticker sets. Like other sticker modification methods, you can only update stickers in sets created by your bot.
• Use English keywords for widest reach. Telegram's sticker search is used globally — English keywords reach the most users, even for localized sticker packs.

See Also

• getStickerSet — retrieve a sticker set and its sticker file_ids
• setStickerEmojiList — change the emoji assigned to a sticker
• addStickerToSet — add a sticker with initial keywords
• createNewStickerSet — create a new sticker set
• Sticker — sticker object with file_id
• StickerSet — sticker set object