uploadStickerFile

Returns: File📎 Accepts filesOfficial docs ↗

Use this method to upload a file with a sticker for later use in the createNewStickerSet, addStickerToSet, or replaceStickerInSet methods (the file can be used multiple times). Returns the uploaded File on success.

Parameters

user_idIntegerRequired

User identifier of sticker file owner

stickerInputFileRequired📎 Files

A file with the sticker in .WEBP, .PNG, .TGS, or .WEBM format. See https://core.telegram.org/stickers for technical requirements. More information on Sending Files »

sticker_formatStringRequired

Values:staticanimatedvideo

Format of the sticker, must be one of "static", "animated", "video"

Returns

On success, the File object is returned.

GramIO Usage

// Upload a static sticker (.WEBP or .PNG)
const file = await bot.api.uploadStickerFile({
  user_id: 123456789,
  sticker: await MediaUpload.path("./sticker.webp"),
  sticker_format: "static",
});

console.log(file.file_id); // Reuse this file_id in createNewStickerSet / addStickerToSet

// Upload an animated sticker (.TGS)
const file = await bot.api.uploadStickerFile({
  user_id: 123456789,
  sticker: await MediaUpload.path("./sticker.tgs"),
  sticker_format: "animated",
});

// Upload a video sticker (.WEBM), then immediately use it in a new sticker set
const file = await bot.api.uploadStickerFile({
  user_id: 123456789,
  sticker: await MediaUpload.path("./sticker.webm"),
  sticker_format: "video",
});

await bot.api.createNewStickerSet({
  user_id: 123456789,
  name: "my_pack_by_mybot",
  title: "My Sticker Pack",
  stickers: [
    {
      sticker: file.file_id,
      emoji_list: ["🎉"],
      format: "video",
    },
  ],
});

// Upload from a URL (Telegram fetches it server-side)
const file = await bot.api.uploadStickerFile({
  user_id: 123456789,
  sticker: await MediaUpload.url("https://example.com/sticker.webp"),
  sticker_format: "static",
});

Errors

Code	Error	Cause
400	Bad Request: USER_NOT_FOUND	user_id is invalid or the user has never interacted with the bot
400	Bad Request: wrong file identifier/HTTP URL specified	The sticker file URL is inaccessible or the file_id is invalid
400	Bad Request: STICKER_INVALID	File format doesn't match sticker_format (e.g. .tgs file with "static")
400	Bad Request: file is too big	Sticker file exceeds Telegram's size limits for the chosen format
400	Bad Request: IMAGE_INVALID	Static sticker dimensions are not 512×512 pixels

Tips & Gotchas

• Match sticker_format to the file extension exactly. .WEBP/.PNG → "static", .TGS → "animated", .WEBM → "video". A mismatch returns STICKER_INVALID.
• The returned file_id can be reused across multiple sticker sets. Cache it instead of uploading the same file repeatedly — the file stays accessible on Telegram's servers.
• Static stickers must be exactly 512×512 pixels. Animated and video stickers have their own strict technical requirements detailed at core.telegram.org/stickers.
• user_id will be the sticker set owner. When you pass this file_id to createNewStickerSet, the set is created on behalf of that user. Make sure the user has started a conversation with your bot.
• Use MediaUpload.path() for local files or MediaUpload.url() for remote files. Both are async — always await them. For in-memory buffers, use MediaUpload.buffer(buf, "sticker.webp") (synchronous).

See Also

• createNewStickerSet
• addStickerToSet
• replaceStickerInSet
• InputSticker
• File
• Media Upload Guide