Emojis

Emoji

Emoji are small images that can be used to convey an idea or emotion. Discord allows users to upload custom emoji to guilds and use them like normal emoji in-chat and when reacting to messages.

Emoji Object

Emoji Structure

Field
Type
Description

id

?snowflake

The ID of the emoji

name 2

string

The name of the emoji (2-32 characters)

roles?

array[snowflake]

The roles allowed to use the emoji

user? 1

partial user object

The user that uploaded the emoji

require_colons?

boolean

Whether this emoji must be wrapped in colons

managed?

boolean

Whether this emoji is managed

animated?

boolean

Whether this emoji is animated

available?

boolean

Whether this emoji can be used; may be false due to loss of premium subscriptions (boosts)

1 Only included for emoji when fetched through the Get Guild Emojis or Get Guild Emoji endpoints by a user with the permission. Always included when fetched from Get Application Emojis or Get Application Emoji.

2 This may be in the case of a custom emoji that has been deleted.

Premium Emoji

Roles with the tag being the guild's integration are considered subscription roles. An emoji cannot have both subscription roles and non-subscription roles. Emoji with subscription roles are considered premium emoji, and count toward a separate limit of 25. Emoji cannot be converted between normal and premium after creation.

Appication Emoji

An application can own up to 2,000 emoji that can only be used by the app. The permission is not required to use these emoji. These emoji do not support role-locking and always require colons. They are never managed or unavailable.

Emoji Example

{  "id": "41771983429993937",  "name": "LUL",  "roles": ["41771983429993000", "41771983429993111"],  "user": {    "id": "306810730055729152",    "username": "owoer",    "avatar": "b3028be18dc56db5722bd750cf69df4e",    "discriminator": "0",    "public_flags": 4194816,    "banner": null,    "accent_color": null,    "global_name": "Eon",    "avatar_decoration_data": null,    "primary_guild": null  },  "require_colons": true,  "managed": false,  "animated": false}

Gateway Reaction Standard Emoji Example

{  "id": null,  "name": "🔥"}

Gateway Reaction Custom Emoji Examples

{  "id": "41771983429993937",  "name": "LUL",  "animated": true}
{  "id": "41771983429993937",  "name": null}

Endpoints

Get Guild Emojis

GET/guilds/{guild.id}/emojis

Returns a list of emoji objects for the given guild. Includes the field if the user has the or permission.

Get Guild Emoji

GET/guilds/{guild.id}/emojis/{emoji.id}

Returns an emoji object for the given guild and emoji IDs. Includes the field if the user has the or permission.

Get Guild Top Emojis

GET/guilds/{guild.id}/top-emojis

Returns the most-used emojis for the given guild.

Response Body

Field
Type
Description

items

array[top emoji object]

The most-used emojis for the guild

Top Emoji Structure

Field
Type
Description

emoji_id

snowflake

The ID of the emoji

emoji_rank

integer

The overall rank of the emoji

Example Response

{  "items": [    {      "emoji_id": "1145727546747535412",      "emoji_rank": 1    },    {      "emoji_id": "1174435954090594505",      "emoji_rank": 2    },    {      "emoji_id": "1029462631163117629",      "emoji_rank": 3    },    {      "emoji_id": "1030570693903011921",      "emoji_rank": 4    },    {      "emoji_id": "1077714345825407067",      "emoji_rank": 5    }  ]}

Get Emoji Guild

GET/emojis/{emoji.id}/guild

Returns a discoverable guild object for the guild that owns the given emoji. This endpoint requires the guild to be discoverable, not be auto-removed, and have guild expression discoverability enabled.

Get Emoji Source

GET/emojis/{emoji.id}/source

Returns an object containing information on the guild or application that owns the given emoji. If the source is a guild, this endpoint requires the guild to be discoverable, not be auto-removed, and have guild expression discoverability enabled.

Response Body

Field
Type
Description

type

string

The type of emoji source

guild

?emoji guild object

The guild that owns the given emoji

application

?emoji application object

The application that owns the given emoji

Emoji Source Type

Value
Description

GUILD

The emoji is uploaded to a guild

APPLICATION

The emoji is uploaded to an application

Emoji Guild Structure

Field
Type
Description

id

snowflake

The ID of the guild

name

string

The name of the guild (2-100 characters)

icon

?string

The guild's icon hash

description

?string

The description for the guild (max 300 characters)

features

array[string]

Enabled guild features

emojis

array[emoji object]

Custom guild emojis

premium_tier

integer

The guild's premium tier (boost level)

premium_subscription_count

integer

The number of premium subscriptions (boosts) the guild currently has

approximate_member_count

integer

Approximate number of total members in the guild

approximate_presence_count

integer

Approximate number of non-offline members in the guild

Emoji Application Structure

Field
Type
Description

id

snowflake

The ID of the application

name

string

The name of the application

Example Response

{  "guild": {    "id": "322850917248663552",    "name": "Official Fortnite",    "icon": "39e9f70c87a3d20dfe02e5f013b417f4",    "emojis": [],    "approximate_member_count": 1068003,    "approximate_presence_count": 163598,    "description": "The Official Fortnite Discord Server! Join to follow news & updates, LFG, and chat about Fortnite Battle Royale.",    "features": [      "ANIMATED_BANNER",      "ANIMATED_ICON",      "AUTO_MODERATION",      "BANNER",      "CHANNEL_ICON_EMOJIS_GENERATED",      "COMMUNITY",      "COMMUNITY_EXP_LARGE_UNGATED",      "DISCOVERABLE",      "FEATURABLE",      "GUILD_MEMBER_VERIFICATION_EXPERIMENT",      "GUILD_WEB_PAGE_VANITY_URL",      "INVITE_SPLASH",      "MEMBER_PROFILES",      "MEMBER_VERIFICATION_GATE_ENABLED",      "NEWS",      "NEW_THREAD_PERMISSIONS",      "PREVIEW_ENABLED",      "PRIVATE_THREADS",      "ROLE_ICONS",      "SEVEN_DAY_THREAD_ARCHIVE",      "SOUNDBOARD",      "THREADS_ENABLED",      "THREE_DAY_THREAD_ARCHIVE",      "VANITY_URL",      "VERIFIED",      "VIP_REGIONS"    ],    "premium_subscription_count": 378,    "premium_tier": 3  },  "application": null,  "type": "GUILD"}

Create Guild Emoji

POST/guilds/{guild.id}/emojis

Creates a new emoji for the guild. Requires the permission. Returns the new emoji object on success. Fires a Guild Emojis Update Gateway event.

Emoji LimitsHow are emoji slots calculated?

Each guild has limits for each type of emoji. The types, or buckets, are:

  • Normal emoji: Default non-animated emoji

  • Animated emoji: Animated emoji

  • Premium emoji: Emoji that is locked to role subscriptions

The default emoji limit is 50. For normal and animated emoji, the maximum is applied individually, and depends on the guild's premium tier and features. Therefore, the maximum number of emoji is calculated as follows:

  • Normal emoji:

  • Animated emoji:

  • Premium emoji: (constant)

If this is confusing, the limits are also summarized in the following table by premium tier. Note that if the guild has the feature, the normal and animated limit is instead 200.

Premium Tier
Normal Emoji
Animated Emoji
Premium Emoji

NONE

50

50

25

TIER_1

100

100

25

TIER_2

150

150

25

TIER_3

250

250

25

JSON Params

Field
Type
Description

name

string

The name of the emoji (2-32 characters)

image

image data

128x128 emoji image

roles?

array[snowflake]

The roles allowed to use this emoji

Modify Guild Emoji

PATCH/guilds/{guild.id}/emojis/{emoji.id}

Modifies the given emoji. For emojis created by the current user, requires either the or permission. For other emojis, requires the permission. Returns the updated emoji object on success. Fires a Guild Emojis Update Gateway event.

JSON Params

Field
Type
Description

name?

string

The name of the emoji (2-32 characters)

roles?

?array[snowflake]

The roles allowed to use this emoji

Delete Guild Emoji

DELETE/guilds/{guild.id}/emojis/{emoji.id}

Deletes the given emoji. For emojis created by the current user, requires either the or permission. For other emojis, requires the permission. Returns a 204 empty response on success. Fires a Guild Emojis Update Gateway event.

Get Application Emojis

GET/applications/{application.id}/emojis

Returns an object containing a list of emoji objects for the given application under the key. Includes the field.

Response Body

Field
Type
Description

items

array[emoji object]

The emojis uploaded to the application

Get Application Emoji

GET/applications/{application.id}/emojis/{emoji.id}

Returns an emoji object for the given application and emoji IDs. Includes the field.

Create Application Emoji

POST/applications/{application.id}/emojis

Creates a new emoji for the application. Returns the new emoji object on success.

JSON Params

Field
Type
Description

name 1

string

The name of the emoji (2-32 characters)

image

image data

128x128 emoji image

1 The names of application emoji must be unique.

Modify Application Emoji

PATCH/applications/{application.id}/emojis/{emoji.id}

Modifies the given emoji. Returns the updated emoji object on success.

JSON Params

Field
Type
Description

name? 1

string

The name of the emoji (2-32 characters)

Delete Application Emoji

DELETE/applications/{application.id}/emojis/{emoji.id}

Delete the given emoji. Returns a 204 empty response on success.