Emoji Resource

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
FieldTypeDescription
id?snowflakeThe ID of the emoji
name 2stringThe name of the emoji (2-32 characters)
roles?array[snowflake]The roles allowed to use the emoji
user? 1partial user objectThe user that uploaded the emoji
require_colons?booleanWhether this emoji must be wrapped in colons
managed?booleanWhether this emoji is managed
animated?booleanWhether this emoji is animated
available?booleanWhether 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 MANAGE_EMOJIS_AND_STICKERS permission.

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

Premium Emoji

Roles with the integration_id tag being the guild's guild_subscription 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.

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
  },
  "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 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 and have emoji/sticker discoverability enabled.

Get Guild Emojis

GET/guilds/{guild.id}/emojis

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

Get Guild Emoji

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

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

Get Guild Top Emojis

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

Returns the most-used emojis for the given guild.

Response Body
FieldTypeDescription
itemsarray[top emoji object]The most-used emojis for the guild
Top Emoji Structure
FieldTypeDescription
emoji_idsnowflakeThe ID of the emoji
emoji_rankintegerThe 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
    }
  ]
}

Create Guild Emoji

POST/guilds/{guild.id}/emojis
Audit Log Reason

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

JSON Params
FieldTypeDescription
namestringThe name of the emoji (2-32 characters)
imageimage data128x128 emoji image
roles?array[snowflake]The roles allowed to use this emoji

Modify Guild Emoji

PATCH/guilds/{guild.id}/emojis/{emoji.id}
Audit Log Reason

Modifies the given emoji. Requires the MANAGE_EMOJIS_AND_STICKERS permission. Returns the updated emoji object on success. Fires a Guild Emojis Update Gateway event.

JSON Params
FieldTypeDescription
name?stringThe 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}
Audit Log Reason

Deletes the given emoji. Requires the MANAGE_EMOJIS_AND_STICKERS permission. Returns a 204 empty response on success. Fires a Guild Emojis Update Gateway event.