replaceStickerInSet

Returns: True📎 Accepts files Official docs ↗

Use this method to replace an existing sticker in a sticker set with a new one. The method is equivalent to calling deleteStickerFromSet, then addStickerToSet, then setStickerPositionInSet. Returns True on success.

Parameters

user_idIntegerRequired

User identifier of the sticker set owner

nameStringRequired

Sticker set name

old_stickerStringRequired

File identifier of the replaced sticker

stickerInputStickerRequired

A JSON-serialized object with information about the added sticker. If exactly the same sticker had already been added to the set, then the set remains unchanged.

Returns

On success, True is returned.

GramIO Usage

Replace a sticker using a new local file:

await bot.api.replaceStickerInSet({
  user_id: 123456789,
  name: "MyStickerSet_by_mybot",
  old_sticker: "CAACAgIAAxkBAAIBb2YKp_OLD_FILE_ID",
  sticker: {
    sticker: await MediaUpload.path("./updated_sticker.webp"),
    format: "static",
    emoji_list: ["✨"],
  },
});

Replace with an existing sticker by file_id, adding keywords:

await bot.api.replaceStickerInSet({
  user_id: 123456789,
  name: "MyStickerSet_by_mybot",
  old_sticker: "CAACAgIAAxkBAAIBb2YKp_OLD",
  sticker: {
    sticker: "CAACAgIAAxkBAAIBb2YKp_NEW",
    format: "static",
    emoji_list: ["🎉", "🥳"],
    keywords: ["party", "celebrate", "happy"],
  },
});

Replace a video sticker uploaded from a URL:

await bot.api.replaceStickerInSet({
  user_id: 123456789,
  name: "MyVideoSet_by_mybot",
  old_sticker: "CAACAgIAAxkBAAIBb2YKp_OLD_VIDEO",
  sticker: {
    sticker: await MediaUpload.url("https://example.com/new_sticker.webm"),
    format: "video",
    emoji_list: ["🔥"],
  },
});

Errors

Code	Error	Cause
400	`Bad Request: STICKERSET_INVALID`	Sticker set doesn't exist or wasn't created by this bot — verify `name` ends with `_by_<botusername>`
400	`Bad Request: STICKER_EMOJI_INVALID`	`emoji_list` contains an invalid or non-emoji character — must be actual emoji codepoints
400	`Bad Request: STICKER_PNG_DIMENSIONS`	Static sticker dimensions are wrong — must be exactly 512×512 px
400	`Bad Request: STICKER_FILE_INVALID`	The replacement file is corrupt, wrong format, or exceeds size limits
400	`Bad Request: wrong file identifier/HTTP URL specified`	The `old_sticker` file_id is invalid or doesn't belong to this sticker set
400	`Bad Request: USER_NOT_FOUND`	`user_id` doesn't correspond to a known Telegram user
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

The operation is atomic in position. replaceStickerInSet preserves the original sticker's position in the set. This is more reliable than manually calling delete + add + reposition, which can fail midway and leave the set inconsistent.
The sticker set must be owned by the bot. The user_id is the set owner (the person who requested it), but the bot must have created the set via createNewStickerSet.
Format must match the set type. You cannot replace a static sticker with a video sticker. The format in InputSticker must match the set's original type.
Duplicate replacement is a no-op. If sticker is the exact same file already in the set, the method returns True but the set is not modified.
old_sticker is the file_id of the sticker to remove. Get current sticker file IDs from getStickerSet — each Sticker object in stickers[] has a file_id.
emoji_list accepts 1–20 emojis. The new sticker's emoji associations are set fresh — the old sticker's emojis are not inherited.

replaceStickerInSet ​

Parameters ​

Returns ​

GramIO Usage ​

Errors ​

Tips & Gotchas ​

See Also ​