sticker_add

Upload an image as a new custom sticker. Stickers work like custom emoji but also carry a description, and names need at least two characters.

Request

{
  "cmd": "sticker_add",
  "name": "good_morning",
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "description": "A cat stretching in the sun"
}

Field	Type	Required	Description
`name`	string	Yes	2 to 64 letters, digits, or underscores. Surrounding spaces are trimmed. Must not match an existing sticker name, ignoring case.
`image`	string	Yes	A base64 data URI in the form `data:image/<type>;base64,<data>`. A plain URL or bare base64 is rejected.
`description`	string	No	Free text, such as alt text. Defaults to `""`. No length limit.

The image type must be in the server’s uploads.sticker_allowed_file_types list, which the handshake sends in uploads. By default that is gif, jpg, jpeg, png, webp, bmp, avif, and tiff.

For PNG, JPEG, GIF, WebP, BMP, and TIFF, the server checks the file signature. The data must really be the type the URI declares.

Response

{
  "cmd": "sticker_add",
  "id": "2",
  "name": "good_morning",
  "fileName": "2.png",
  "description": "A cat stretching in the sun",
  "added": true
}

id is a string of digits. IDs start at "0", and each new sticker gets one more than the highest existing ID. Sticker and emoji IDs are counted separately.
fileName is <id>.<extension>. Load the image from GET /stickers/{fileName}. GET /stickers/{id} also works.

The server doesn’t broadcast new stickers. Other clients see them the next time they call sticker_list.

Permissions

Requires manage_emojis. There is no separate sticker permission. A user in timeout gets a rate_limit frame instead.

Errors

`val`	When
`name: Required`	`name` is missing. The same pattern applies to `image`.
`name: Expected string, received number`	`name`, `image`, or `description` isn’t a string.
`Failed to add sticker 'good_morning'. It may already exist or there was a storage error.`	Any other failure: the name is invalid or taken, the image is not a valid data URI, the type isn’t allowed, the data doesn’t match the type, or the save failed. The quoted text is the `name` you sent.

See also