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

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

² 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.

Appication Emoji

An application can own up to 2000 emoji that can only be used by the app. The USE_EXTERNAL_EMOJIS 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 Emoji 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 emoji/sticker discoverability enabled.

Get Emoji 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 emoji/sticker discoverability enabled.

Response Body

Emoji Source Type

Emoji Guild Structure

Emoji Application Structure

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"
}

Get Guild Emojis

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

Get Guild Emoji

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

Get Guild Top Emojis

Returns the most-used emojis for the given guild.

Response Body

Top Emoji Structure

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

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

JSON Params

Modify Guild Emoji

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

JSON Params

Delete Guild Emoji

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

Get Application Emojis

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

Response Body

Get Application Emoji

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

Create Application Emoji

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

JSON Params

¹ The names of application emoji must be unique.

Modify Application Emoji

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

JSON Params

Delete Application Emoji

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