Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
9.1 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Guild emojis
description: Guild emoji objects and the routes to list, create, clone, rename and delete them.
---

import RouteHeader from '@/components/RouteHeader.astro';

A guild emoji is a custom image that one guild owns and its members use in messages and reactions. To look up one emoji without joining its guild, use [Get emoji metadata](/http-api/expressions/#get-emoji-metadata).

## Guild emoji object

An emoji as the API returns it.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| id | snowflake | The ID of the emoji |
| name | string | The name of the emoji (2-32 characters) |
| animated | boolean | Whether the image is animated |
| user?<sup>1</sup> | [partial user](/http-api/users/#partial-user-object) object | The account that uploaded the emoji |

<sup>1</sup> Only [List guild emojis](#list-guild-emojis) includes it

### Example

```json
{
  "id": "1501314428688998182",
  "name": "party_parrot",
  "animated": true
}
```

## Emoji create object

The name and image for one new emoji.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| name | string | The name of the emoji (2-32 characters, ASCII letters, digits and underscore) |
| image<sup>1</sup> | base64 string | The emoji image as base64 |

<sup>1</sup> You can include a data URL prefix. The decoded image can be at most the `emoji_max_size` [limit key](/http-api/instance/#limit-keys), 524288 bytes by default. The API accepts PNG, JPEG, WebP, GIF, APNG, AVIF, HEIC, HEIF, JXL and SVG, but not animated AVIF

### Example

```json
{
  "name": "party_parrot",
  "image": "data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAI="
}
```

## Emoji bulk create response object

The result of a bulk create, with each submitted item in either `success` or `failed`.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| success | array[[guild emoji](#guild-emoji-object) object] | The emojis this request created |
| failed | array[[expression creation failure](#expression-creation-failure-object) object] | The items Fluxer rejected |

## Expression creation failure object

One item a bulk creation rejected.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| name | string | The name submitted for the item |
| error | string | The failure message, in the account's locale |

## List guild emojis

<RouteHeader method="GET" path="/v1/guilds/{guild_id}/emojis" bot />

Returns the guild's [guild emoji objects](#guild-emoji-object), each with the `user` who uploaded it. An emoji whose uploader cannot be resolved is left out. You need to be a member of the guild.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[guild emoji](#guild-emoji-object) object] | Emojis were returned |

The rate limit is 60 requests per 10 seconds, on the `guild:emojis:list::guild_id` bucket.

## Create guild emoji

<RouteHeader method="POST" path="/v1/guilds/{guild_id}/emojis" bot auditReason />

Creates an emoji and returns its [guild emoji object](#guild-emoji-object). You need [CREATE_EXPRESSIONS](/http-api/permissions/). A guild can have 500 emojis, or the [max_guild_emojis](/http-api/instance/#limit-keys) limit if the instance sets one. A guild with [UNLIMITED_EMOJI](/http-api/guilds/#guild-features) can have 999999.

### JSON body

The body is an [emoji create object](#emoji-create-object).

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [guild emoji](#guild-emoji-object) object | The emoji was created |
| 400 | [error response](/http-api/#error-response) | `MAX_EMOJIS` when the guild is full, or `INVALID_FORM_BODY` when the image is too large or in an unsupported format |
| 403 | [error response](/http-api/#error-response) | `CONTENT_BLOCKED` when the name or image is blocked |

Fluxer sends a [Guild Emojis Update](/gateway/events/#guild-emojis-update) event and records an [`EMOJI_CREATE`](/http-api/guild-audit-logs/#audit-actions) audit entry.

The rate limit is 10 requests per 30 seconds, on the `guild:emoji:create::guild_id` bucket.

## Bulk create guild emojis

<RouteHeader method="POST" path="/v1/guilds/{guild_id}/emojis/bulk" bot auditReason />

Creates several emojis in one request and returns an [emoji bulk create response object](#emoji-bulk-create-response-object). You need [CREATE_EXPRESSIONS](/http-api/permissions/).

The response is 200 even when every item fails. An item goes into `failed` when the guild is full or the API can't use its image, and the rest of the batch still runs.

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| emojis | array[[emoji create object](#emoji-create-object)] | The emojis to create (1-50) |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [emoji bulk create response](#emoji-bulk-create-response-object) object | Fluxer attempted every item |
| 400 | [error response](/http-api/#error-response) | `INVALID_FORM_BODY` when the list is empty or over 50 items, or an item has an invalid name |
| 403 | [error response](/http-api/#error-response) | `CONTENT_BLOCKED` when any item name is blocked, and nothing is created |

Fluxer sends one [Guild Emojis Update](/gateway/events/#guild-emojis-update) event and records an [`EMOJI_CREATE`](/http-api/guild-audit-logs/#audit-actions) audit entry for each created emoji.

The rate limit is 6 requests per minute, on the `guild:emoji:bulk_create::guild_id` bucket.

## Clone guild emoji

<RouteHeader method="POST" path="/v1/guilds/{guild_id}/emojis/clone" bot auditReason />

Copies an emoji from any guild into the guild in the path and returns the new [guild emoji object](#guild-emoji-object), which keeps the source emoji's name. You need [CREATE_EXPRESSIONS](/http-api/permissions/) in the target guild. The source guild needs [CLONE_EMOJI_ENABLED](/http-api/guilds/#guild-features).

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| source_emoji_id | snowflake | The ID of the emoji to copy |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [guild emoji](#guild-emoji-object) object | The emoji was cloned |
| 400 | [error response](/http-api/#error-response) | `MAX_EMOJIS` when the target guild is full |
| 403 | [error response](/http-api/#error-response) | `MISSING_ACCESS` when the source guild does not allow cloning |
| 404 | [error response](/http-api/#error-response) | `UNKNOWN_EMOJI` when the source emoji does not exist |

Fluxer sends a [Guild Emojis Update](/gateway/events/#guild-emojis-update) event in the target guild and records an [`EMOJI_CREATE`](/http-api/guild-audit-logs/#audit-actions) audit entry.

The rate limit is 10 requests per 30 seconds, on the `guild:emoji:clone::guild_id` bucket.

## Modify guild emoji

<RouteHeader method="PATCH" path="/v1/guilds/{guild_id}/emojis/{emoji_id}" bot auditReason />

Renames an emoji and returns its [guild emoji object](#guild-emoji-object). The uploader needs [CREATE_EXPRESSIONS](/http-api/permissions/) and anyone else needs [MANAGE_EXPRESSIONS](/http-api/permissions/).

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| name | string | The new name of the emoji (2-32 characters, ASCII letters, digits and underscore) |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [guild emoji](#guild-emoji-object) object | The emoji was renamed |
| 403 | [error response](/http-api/#error-response) | `CONTENT_BLOCKED` when the name is blocked |
| 404 | [error response](/http-api/#error-response) | `UNKNOWN_EMOJI` when the emoji is not in this guild |

Fluxer sends a [Guild Emojis Update](/gateway/events/#guild-emojis-update) event and records an [`EMOJI_UPDATE`](/http-api/guild-audit-logs/#audit-actions) audit entry.

The rate limit is 20 requests per 10 seconds, on the `guild:emoji:update::guild_id` bucket.

## Delete guild emoji

<RouteHeader method="DELETE" path="/v1/guilds/{guild_id}/emojis/{emoji_id}" bot auditReason />

Deletes an emoji. The uploader needs [CREATE_EXPRESSIONS](/http-api/permissions/) and anyone else needs [MANAGE_EXPRESSIONS](/http-api/permissions/).
### Query parameters

| Field | Type | Description |
| --- | --- | --- |
| purge? | boolean | Whether to delete the image file too (default false) |

:::caution[Purging cannot be undone]
With `purge`, Fluxer deletes the image file and you can't get it back. Without it, the image stays available through the [Media Proxy](/media-proxy/routes/#image-asset-contract).
:::

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The emoji was deleted |
| 403 | [error response](/http-api/#error-response) | `MISSING_ACCESS` when `purge` is true and the guild lacks [EXPRESSION_PURGE_ALLOWED](/http-api/guilds/#guild-features) |
| 404 | [error response](/http-api/#error-response) | `UNKNOWN_EMOJI` when the emoji is not in this guild |

Fluxer sends a [Guild Emojis Update](/gateway/events/#guild-emojis-update) event and records an [`EMOJI_DELETE`](/http-api/guild-audit-logs/#audit-actions) audit entry.

The rate limit is 10 requests per 30 seconds, on the `guild:emoji:delete::guild_id` bucket. The route also allows 300 requests per day, on the `guild:emoji:delete:daily::guild_id` bucket.