getCustomEmojiStickers

Returns: Sticker[]Official docs ↗

Use this method to get information about custom emoji stickers by their identifiers. Returns an Array of Sticker objects.

Parameters

custom_emoji_idsString[]Required

A JSON-serialized list of custom emoji identifiers. At most 200 custom emoji identifiers can be specified.

Returns

On success, an array of Sticker objects is returned.

GramIO Usage

// Fetch sticker info for a known custom emoji ID
const stickers = await bot.api.getCustomEmojiStickers({
    custom_emoji_ids: ["5368324170671202286"],
});
console.log(stickers[0]?.emoji); // The associated base emoji character

// Resolve custom emoji entities found in an incoming message
bot.on("message", async (ctx) => {
    const entities = ctx.payload.entities ?? [];
    const emojiIds = entities
        .filter((e) => e.type === "custom_emoji")
        .map((e) => e.custom_emoji_id!);

    if (emojiIds.length === 0) return;

    const stickers = await bot.api.getCustomEmojiStickers({
        custom_emoji_ids: emojiIds,
    });
    const setNames = [...new Set(stickers.map((s) => s.set_name).filter(Boolean))];
    await ctx.send(`Custom emoji from pack(s): ${setNames.join(", ")}`);
});

// Batch-fetch more than 200 IDs in chunks
async function getCustomEmojiStickersInBatches(bot: Bot, ids: string[]) {
    const results = [];
    for (let i = 0; i < ids.length; i += 200) {
        const chunk = ids.slice(i, i + 200);
        const stickers = await bot.api.getCustomEmojiStickers({
            custom_emoji_ids: chunk,
        });
        results.push(...stickers);
    }
    return results;
}

Errors

Code	Error	Cause
400	Bad Request: STICKER_ID_INVALID	One or more custom emoji IDs are invalid or have been deleted
400	Bad Request: too many custom emoji ids	More than 200 IDs in a single request — split into chunks of ≤ 200
429	Too Many Requests: retry after N	Rate limit hit — check retry_after, use the auto-retry plugin

TIP

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

Tips & Gotchas

• Maximum 200 IDs per request. Batch any larger set into chunks of 200 — see the example above. Exceeding the limit returns a 400 error.
• Custom emoji IDs come from message entities. When a message contains a custom_emoji entity, its custom_emoji_id field holds the ID. Use ctx.payload.entities to extract them.
• The returned Sticker objects have type: "custom_emoji". The custom_emoji_id field on each returned sticker matches the ID you requested.
• Use set_name to find the sticker pack. Then call getStickerSet with that name to retrieve the full pack and all its stickers.
• IDs are stable but stickers can be removed. A custom emoji ID won't change when a pack is updated, but if the sticker is deleted from the set, the ID becomes invalid and the method returns an error.
• Order is not guaranteed. The returned array does not necessarily match the order of custom_emoji_ids you sent — match by custom_emoji_id field if order matters.

See Also

• getStickerSet — get the full sticker pack for a custom emoji
• Sticker — the returned type