setStickerSetThumbnail

Returns: True📎 Accepts files Official docs ↗

Use this method to set the thumbnail of a regular or mask sticker set. The format of the thumbnail file must match the format of the stickers in the set. Returns True on success.

Parameters

nameStringRequired

Sticker set name

user_idIntegerRequired

User identifier of the sticker set owner

thumbnailInputFileStringOptional📎 Files

A .WEBP or .PNG image with the thumbnail, must be up to 128 kilobytes in size and have a width and height of exactly 100px, or a .TGS animation with a thumbnail up to 32 kilobytes in size (see https://core.telegram.org/stickers#animation-requirements for animated sticker technical requirements), or a .WEBM video with the thumbnail up to 32 kilobytes in size; see https://core.telegram.org/stickers#video-requirements for video sticker technical requirements. Pass a file\_id as a String to send a file that already exists on the Telegram servers, pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one using multipart/form-data. More information on Sending Files ». Animated and video sticker set thumbnails can't be uploaded via HTTP URL. If omitted, then the thumbnail is dropped and the first sticker is used as the thumbnail.

formatStringRequired

Values:staticanimatedvideo

Format of the thumbnail, must be one of "static" for a .WEBP or .PNG image, "animated" for a .TGS animation, or "video" for a .WEBM video

Returns

On success, True is returned.

GramIO Usage

// Set a static thumbnail for a regular sticker set (WEBP, 100×100px, max 128KB)
await bot.api.setStickerSetThumbnail({
  name: "my_pack_by_mybot",
  user_id: 123456789,
  thumbnail: await MediaUpload.path("./thumbnail.webp"),
  format: "static",
});

// Set an animated thumbnail for an animated sticker set (TGS, max 32KB)
await bot.api.setStickerSetThumbnail({
  name: "my_animated_pack_by_mybot",
  user_id: 123456789,
  thumbnail: await MediaUpload.path("./thumbnail.tgs"),
  format: "animated",
});

// Set a video thumbnail for a video sticker set (WEBM, max 32KB)
await bot.api.setStickerSetThumbnail({
  name: "my_video_pack_by_mybot",
  user_id: 123456789,
  thumbnail: await MediaUpload.path("./thumbnail.webm"),
  format: "video",
});

// Remove the custom thumbnail — falls back to the first sticker in the set
await bot.api.setStickerSetThumbnail({
  name: "my_pack_by_mybot",
  user_id: 123456789,
  format: "static",
  // omitting thumbnail removes it
});

Errors

Code	Error	Cause
400	`Bad Request: not enough rights to change sticker set`	The `user_id` is not the owner of the sticker set, or the bot didn't create the set
400	`Bad Request: STICKERSET_INVALID`	The sticker set name doesn't exist or doesn't belong to this bot
400	`Bad Request: wrong file type`	The uploaded file format doesn't match the `format` parameter — ensure the file extension and content match
400	`Bad Request: STICKER_PNG_DIMENSIONS`	The static thumbnail is not exactly 100×100 pixels
400	`Bad Request: file is too big`	Thumbnail exceeds the size limit — 128KB for static, 32KB for animated/video
400	`Bad Request: wrong file identifier/HTTP URL specified`	Bad file_id or inaccessible URL — animated/video thumbnails cannot be uploaded via HTTP URL
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

Thumbnail format must match the sticker set format. A static sticker set requires a static ("static") thumbnail; animated sets require animated ("animated"); video sets require video ("video"). Mismatches return an error.
Static thumbnails: exactly 100×100px. Even 101×101 will fail. Export your thumbnail at exactly this size.
Size limits differ by type. Static thumbnails may be up to 128KB; animated (.TGS) and video (.WEBM) thumbnails must be under 32KB each.
Animated and video thumbnails cannot use HTTP URLs. Only file uploads or existing file_ids work for TGS/WEBM thumbnails — unlike static thumbnails which can use URLs.
Omitting thumbnail removes the custom thumbnail. The set then falls back to displaying the first sticker (position 0) as its cover. Use setStickerPositionInSet to control which sticker that is.
user_id must be the sticker set owner. Pass the Telegram user ID of whoever owns the set (the bot creator's user ID, typically).

setStickerSetThumbnail ​

Parameters ​

Returns ​

GramIO Usage ​

Errors ​

Tips & Gotchas ​

See Also ​