REST: Emoji

Custom emoji of the community: list, images and (with Manage emoji) upload, rename and delete. Generated from mnema-talk v3.3.13 (cca4f0fdb723).

Add a custom emoji

POST /api/admin/emoji

multipart/form-data with name (2 to 32 characters of a-z, 0-9 and _; upper case is folded) and file, a PNG, GIF or WebP of at most 256 KiB. The image is decoded and redrawn (at most 128x128, no metadata); SVG, JPEG and animated WebP are refused. Needs Manage emoji. Broadcasts emoji_changed.

Authentication: Session cookie

Request body (multipart/form-data, required): object

FieldTypeDescription
file (required)string (binary)PNG, GIF or WebP, at most 256 KiB.
name (required)stringEmoji name.

Responses

StatusMeaningBody
201Created emoji.Emoji
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage emoji permission, or cross-origin request rejected.ErrorResponse
409CONFLICT: the name is taken or the instance limit is reached.ErrorResponse
413PAYLOAD_TOO_LARGE: body or file exceeds the limit (1 MiB for JSON).ErrorResponse
415UNSUPPORTED_MEDIA_TYPE: the file type is not allowed.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: a dependency (database, file storage) is not available, or image processing is busy.ErrorResponse
Emoji
FieldTypeDescription
animated (required)booleanAnimated emoji are GIFs and have a still frame for reduced motion.
created_at (required)string
id (required)string (uuid)
name (required)string
still_urlstringStillURL is the first frame (animated emoji only).
url (required)stringURL serves the image; it changes with the content (the v parameter), so it may be cached for good.

Delete a custom emoji

DELETE /api/admin/emoji/{id}

Messages and reactions that used it show :name: as text from now on. Needs Manage emoji. Broadcasts emoji_changed.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesEmoji ID.

Responses

StatusMeaningBody
204Deleted.
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage emoji permission, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse

Rename a custom emoji

PATCH /api/admin/emoji/{id}

Messages and reactions keep pointing at the emoji by id, so they follow the new name. Needs Manage emoji. Broadcasts emoji_changed.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesEmoji ID.

Request body (application/json, required): RenameRequest

FieldTypeDescription
name (required)string

Responses

StatusMeaningBody
200Renamed emoji.Emoji
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
403FORBIDDEN: missing the Manage emoji permission, or cross-origin request rejected.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
409CONFLICT: the name is taken.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
Emoji
FieldTypeDescription
animated (required)booleanAnimated emoji are GIFs and have a still frame for reduced motion.
created_at (required)string
id (required)string (uuid)
name (required)string
still_urlstringStillURL is the first frame (animated emoji only).
url (required)stringURL serves the image; it changes with the content (the v parameter), so it may be cached for good.

List custom emoji

GET /api/emoji

Every custom emoji of the instance, by name, with the instance limit. Members use them as <:name:id> in messages and reactions.

Authentication: Session cookie

Responses

StatusMeaningBody
200Custom emoji.List
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
List
FieldTypeDescription
emoji (required)Emoji[]
limit (required)integerLimit is how many custom emoji the instance allows (EMOJI_MAX).

Custom emoji image

GET /api/emoji/{id}/image

The redrawn PNG or GIF of the emoji. The v parameter is the content hash of the emoji's URL: the response is cacheable for a year.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesEmoji ID.
vquerystringnoContent hash from the emoji's URL.

Responses

StatusMeaningBody
200Image.string
304Not modified (If-None-Match).
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: a dependency (database, file storage) is not available.ErrorResponse

Custom emoji still frame

GET /api/emoji/{id}/still

The first frame of an animated emoji as a PNG, for members who reduce motion. 404 when the emoji has no still frame (it is not animated). The v parameter is the content hash of the emoji's URL: the response is cacheable for a year.

Authentication: Session cookie

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)yesEmoji ID.
vquerystringnoContent hash from the emoji's URL.

Responses

StatusMeaningBody
200Image.string
304Not modified (If-None-Match).
400Invalid input (INVALID_INPUT): malformed JSON, unknown JSON fields, bad IDs or failed validation.ErrorResponse
401No valid session (UNAUTHORIZED): missing, expired or revoked cookie, or the account was disabled.ErrorResponse
404NOT_FOUND: the resource, or the route, does not exist.ErrorResponse
429RATE_LIMITED: too many requests.ErrorResponse
500INTERNAL_ERROR: sanitized server failure.ErrorResponse
503UNAVAILABLE: a dependency (database, file storage) is not available.ErrorResponse

Something wrong on this page? Tell us.