Skip to content

emoji.mdx

Latest commit

 

History

History
247 lines (188 loc) · 12.2 KB

emoji.mdx

File metadata and controls

247 lines (188 loc) · 12.2 KB
Raw
title Emoji Resource
sidebarTitle Emoji
description Reference for Discord emoji objects and management endpoints.

import {ManualAnchor} from '/snippets/manualanchor.jsx' import {Route} from '/snippets/route.jsx'

Routes for controlling emojis do not follow the normal rate limit conventions. These routes are specifically limited on a per-guild basis to prevent abuse. This means that the quota returned by our APIs may be inaccurate, and you may encounter 429s.

Emoji Object

###### Emoji Structure
Field Type Description
id ?snowflake emoji id
name ?string* emoji name (2-32 alphanumeric characters and underscores)
roles? array of role ids roles allowed to use this emoji
user? user object user that created this emoji
require_colons? boolean whether this emoji must be wrapped in colons**
managed? boolean whether this emoji is managed by an integration
animated? boolean whether this emoji is animated
available? boolean whether this emoji can be used, may be false due to loss of Server Boosts
  • This field can only be null in reaction emoji objects. ** The requires_colons field is only set to false for synced subscriber emotes when the Twitch Integration is setup.
###### Premium Emojis

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. Emojis with subscription roles are considered premium emojis, and count toward a separate limit of 25. Emojis cannot be converted between normal and premium after creation.

###### Emoji Formats

Emojis can be uploaded as JPEG, PNG, GIF, WebP, and AVIF formats. All emojis, regardless of original format, can be served as WebP. We highly recommend that developers use the .webp extension when fetching emojis so they're rendered as WebP for maximum performance and compatibility. The Discord client uses WebP for all emojis displayed in-app.

Non-animated WebP emojis can be requested using the .webp file extension. For animated WebP emojis, use the .webp extension with the ?animated=true query parameter.

###### Application-Owned Emojis

An application can own up to 2,000 emojis that can only be used by that app. App emojis can be managed using the API with a bot token or through the "Emoji" tab on the developer portal. The USE_EXTERNAL_EMOJIS permission is not required to use app emojis. The user field of an app emoji object represents the team member that uploaded the emoji from the developer portal, or the bot user if uploaded using the API.

###### Emoji Example 
{
  "id": "41771983429993937",
  "name": "LUL",
  "roles": ["41771983429993000", "41771983429993111"],
  "user": {
    "username": "Luigi",
    "discriminator": "0002",
    "id": "96008815106887111",
    "avatar": "5500909a3274e1812beb4e8de6631111",
    "public_flags": 131328
  },
  "require_colons": true,
  "managed": false,
  "animated": false
}
###### Standard Emoji Example 
{
  "id": null,
  "name": "🔥"
}
###### Custom Emoji Examples In `MESSAGE_REACTION_ADD`, `MESSAGE_REACTION_REMOVE` and `MESSAGE_REACTION_REMOVE_EMOJI` gateway events `animated` will be returned for animated emojis. In `MESSAGE_REACTION_ADD` and `MESSAGE_REACTION_REMOVE` gateway events `name` may be `null` when custom emoji data is not available (for example, if it was deleted from the guild). 
{
  "id": "41771983429993937",
  "name": "LUL",
  "animated": true
}
{
  "id": "41771983429993937",
  "name": null
}

List Guild Emojis

/guilds/{guild.id}/emojis

Returns a list of emoji objects for the given guild. Includes user fields if the bot has the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission.

Get Guild Emoji

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

Returns an emoji object for the provided emoji id in the given guild. Includes the user field if the bot has the MANAGE_GUILD_EXPRESSIONS permission, or if the bot created the emoji and has the CREATE_GUILD_EXPRESSIONS permission.

Create Guild Emoji

/guilds/{guild.id}/emojis

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

Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to upload an emoji larger than this limit will fail and return 400 Bad Request and an error message, but not a [JSON status code](/developers/topics/opcodes-and-status-codes#json). We highly recommend that developers use the `.webp` extension when fetching emojis so they're rendered as WebP for maximum performance and compatibility. See the [Emoji Formats](/developers/resources/emoji#emoji-object-emoji-formats) section above for more details. This endpoint supports the `X-Audit-Log-Reason` header. ###### JSON Params
Field Type Description
name string name of the emoji
image image data the 128x128 emoji image
roles array of snowflakes roles allowed to use this emoji

Modify Guild Emoji

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

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

All parameters to this endpoint are optional. This endpoint supports the `X-Audit-Log-Reason` header. ###### JSON Params
Field Type Description
name string name of the emoji
roles ?array of snowflakes roles allowed to use this emoji

Delete Guild Emoji

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

Delete the given emoji. For emojis created by the current user, requires either the CREATE_GUILD_EXPRESSIONS or MANAGE_GUILD_EXPRESSIONS permission. For other emojis, requires the MANAGE_GUILD_EXPRESSIONS permission. Returns 204 No Content on success. Fires a Guild Emojis Update Gateway event.

This endpoint supports the `X-Audit-Log-Reason` header.

List Application Emojis

/applications/{application.id}/emojis

Returns an object containing a list of emoji objects for the given application under the items key. Includes a user object for the team member that uploaded the emoji from the developer portal, or for the bot user if uploaded directly through the API.

{
  "items": [
    {
      "id": "41771983429993937",
      "name": "LUL",
      "roles": [],
      "user": {
        "username": "Luigi",
        "discriminator": "0002",
        "id": "96008815106887111",
        "avatar": "5500909a3274e1812beb4e8de6631111",
        "public_flags": 131328
      },
      "require_colons": true,
      "managed": false,
      "animated": false
    }
  ]
}

Get Application Emoji

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

Returns an emoji objeect for the provided emoji id and the given application. Includes the user field.

Create Application Emoji

/applications/{application.id}/emojis

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

Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to upload an emoji larger than this limit will fail and return `400 Bad Request` and an error message, but not a [JSON status code](/developers/topics/opcodes-and-status-codes#json). We highly recommend that developers use the `.webp` extension when fetching emojis so they're rendered as WebP for maximum performance and compatibility. See the [Emoji Formats](/developers/resources/emoji#emoji-object-emoji-formats) section above for more details. ###### JSON Params
Field Type Description
name string name of the emoji
image image data the 128x128 emoji image

Modify Application Emoji

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

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

###### JSON Params
Field Type Description
name string name of the emoji

Delete Application Emoji

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

Delete the given emoji. Returns 204 No Content on success.