Skip to main content
Osmium supports stickers and custom emoji through the sticker pack system.

Sticker Packs

Stickers are organized into packs that can contain either stickers or custom emoji:
message StickerPack {
  enum Type {
    UNKNOWN = 0;
    STICKER = 1;
    EMOJI = 2;
  }

  fixed64 id = 1;  // @snowflake<StickerPack>
  Type type = 2;
  string name = 3;
  repeated media.File stickers = 4;
}
id
fixed64
Snowflake identifier for the sticker pack
type
Type
Pack type: UNKNOWN, STICKER, or EMOJI
name
string
Display name of the sticker pack
stickers
File[]
Array of sticker files in this pack. See File structure

Pack Types

  • STICKER: Contains regular stickers for use in messages
  • EMOJI: Contains custom emoji that can be used inline in text
  • UNKNOWN: Default/unspecified type

Get Saved Stickers

Retrieve the user’s saved sticker packs:
message GetSavedStickers {
  optional fixed64 since = 1;
}
Method: media.getSavedStickers
since
fixed64
Only return packs updated after this timestamp (for incremental updates)

Response

message SavedStickers {
  repeated StickerPack saved_packs = 1;
}
saved_packs
StickerPack[]
Array of saved sticker packs

Example

const response = await client.call('media.getSavedStickers', {});

for (const pack of response.saved_packs) {
  console.log(`Pack: ${pack.name} (${pack.type})`);
  console.log(`Stickers: ${pack.stickers.length}`);
}

Incremental Updates

// Get only packs updated since last check
const lastUpdate = getLastUpdateTimestamp();

const response = await client.call('media.getSavedStickers', {
  since: lastUpdate
});

// Only returns packs modified after lastUpdate
processUpdatedPacks(response.saved_packs);

Get Sticker Pack

Retrieve a specific sticker pack by reference:
message GetStickerPack {
  refs.StickerPackRef pack = 1;
}
Method: stickers.getStickerPack Returns: StickerPack
pack
StickerPackRef
required
Reference to the sticker pack to retrieve

Example

const pack = await client.call('stickers.getStickerPack', {
  pack: {
    id: packId
  }
});

console.log(`${pack.name}: ${pack.stickers.length} stickers`);

Get Sticker Files

Retrieve file data for specific stickers:
message GetStickerFiles {
  repeated fixed64 sticker_ids = 1;  // @snowflake<Sticker>
}
Method: stickers.getStickerFiles Returns: media.Files
sticker_ids
fixed64[]
required
Array of sticker snowflake IDs to retrieve

Example

const files = await client.call('stickers.getStickerFiles', {
  sticker_ids: [stickerId1, stickerId2, stickerId3]
});

for (const file of files.files) {
  console.log(`File: ${file.filename}, Size: ${file.size} bytes`);
}

Add Sticker to Pack

Add a new sticker to an existing pack:
message AddStickerToPack {
  refs.StickerPackRef pack = 1;
  media.MediaRefUploadedFile sticker = 2;
}
Method: stickers.addStickerToPack
pack
StickerPackRef
required
Reference to the pack to add the sticker to
sticker
MediaRefUploadedFile
required
The uploaded sticker file with metadata. See Upload

Example

// First, upload the sticker file
const uploadedFile = await uploadStickerFile('sticker.png');

// Then add to pack
await client.call('stickers.addStickerToPack', {
  pack: { id: packId },
  sticker: {
    file: uploadedFile,
    filename: 'sticker.png',
    mimetype: 'image/png',
    metadata: {
      image: {
        width: 512,
        height: 512
      }
    }
  }
});

Adding Custom Emoji

const uploadedEmoji = await uploadStickerFile('custom_emoji.png');

await client.call('stickers.addStickerToPack', {
  pack: { id: emojiPackId },
  sticker: {
    file: uploadedEmoji,
    filename: 'thumbs_up.png',
    mimetype: 'image/png',
    metadata: {
      custom_emoji: {
        width: 128,
        height: 128,
        emoji: '👍',
        pack: { id: emojiPackId }
      }
    }
  }
});

Remove Sticker from Pack

Remove a sticker from a pack:
message RemoveStickerFromPack {
  refs.StickerPackRef pack = 1;
  fixed64 sticker_id = 2;  // @snowflake<Sticker>
}
Method: stickers.removeStickerFromPack
pack
StickerPackRef
required
Reference to the pack containing the sticker
sticker_id
fixed64
required
Snowflake ID of the sticker to remove

Example

await client.call('stickers.removeStickerFromPack', {
  pack: { id: packId },
  sticker_id: stickerId
});

Sticker Workflow

Creating a Sticker Pack

  1. Create a new sticker pack (method not shown in proto, likely stickers.createStickerPack)
  2. Upload sticker files using the chunked upload system
  3. Add each sticker to the pack using addStickerToPack

Using Stickers in Messages

Stickers can be sent as message attachments using their file reference:
const message = await client.call('messages.sendMessage', {
  chat_id: chatId,
  content: {
    media: [
      {
        file: {
          file: stickerFile
        }
      }
    ]
  }
});

Best Practices

Sticker Dimensions

  • Regular stickers: 512x512 pixels recommended
  • Custom emoji: 128x128 or 256x256 pixels
  • Format: PNG with transparency preferred

Pack Management

  • Organize stickers into themed packs
  • Keep pack sizes reasonable (20-50 stickers)
  • Use descriptive pack names
  • Separate stickers and emoji into different packs

Caching

  • Cache sticker packs locally
  • Use since parameter for incremental updates
  • Preload frequently used sticker packs

Build docs developers (and LLMs) love