> ## Documentation Index
> Fetch the complete documentation index at: https://discord-platform-username.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Emoji Resource

> Reference for Discord emoji objects and management endpoints.

export const Route = ({method, children}) => {
  return <div className="MDXRoute">
      <span className={"verb" + " " + method.toLowerCase()}>{method}</span>
      <span className="url">{children}</span>
    </div>;
};

export const ManualAnchor = ({id}) => {
  return <div className="MDXManualAnchor" id={id}></div>;
};

<Warning>
  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.
</Warning>

### Emoji Object

<ManualAnchor id="emoji-object-emoji-structure" />

###### Emoji Structure

| Field            | Type                                                                   | Description                                                               |
| ---------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| id               | ?snowflake                                                             | [emoji id](/developers/reference#image-formatting)                        |
| name             | ?string (can be null only in reaction emoji objects)                   | emoji name                                                                |
| roles?           | array of [role](/developers/topics/permissions#role-object) object ids | roles allowed to use this emoji                                           |
| user?            | [user](/developers/resources/user#user-object) object                  | user that created this 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 Server Boosts |

<ManualAnchor id="emoji-object-premium-emoji" />

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

<ManualAnchor id="emoji-object-emoji-formats" />

###### Emoji Formats

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

Still WebP emoji can be requested using the `.webp` file extension. For animated WebP emoji, use the `.webp` extension with the `?animated=true` query parameter.

<ManualAnchor id="emoji-object-applicationowned-emoji" />

###### Application-Owned Emoji

An application can own up to 2000 emojis that can only be used by that app.
App emojis can be managed using the API with a bot token, or using the app's settings in the 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 app's settings, or the bot user if uploaded using the API.

<ManualAnchor id="emoji-object-emoji-example" />

###### Emoji Example

```json theme={null}
{
  "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
}
```

<ManualAnchor id="emoji-object-standard-emoji-example" />

###### Standard Emoji Example

```json theme={null}
{
  "id": null,
  "name": "🔥"
}
```

<ManualAnchor id="emoji-object-custom-emoji-examples" />

###### Custom Emoji Examples

<Info>
  In `MESSAGE_REACTION_ADD`, `MESSAGE_REACTION_REMOVE` and `MESSAGE_REACTION_REMOVE_EMOJI` gateway events `animated` will be returned for animated emoji.
</Info>

<Info>
  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).
</Info>

```json theme={null}
{
  "id": "41771983429993937",
  "name": "LUL",
  "animated": true
}
```

```json theme={null}
{
  "id": "41771983429993937",
  "name": null
}
```

## List Guild Emojis

<Route method="GET">/guilds/[\{guild.id}](/developers/resources/guild#guild-object)/emojis</Route>

Returns a list of [emoji](/developers/resources/emoji#emoji-object) objects for the given guild. Includes `user` fields if the bot has the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission.

## Get Guild Emoji

<Route method="GET">/guilds/[\{guild.id}](/developers/resources/guild#guild-object)/emojis/[\{emoji.id}](/developers/resources/emoji#emoji-object)</Route>

Returns an [emoji](/developers/resources/emoji#emoji-object) object for the given guild and emoji IDs. 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

<Route method="POST">/guilds/[\{guild.id}](/developers/resources/guild#guild-object)/emojis</Route>

Create a new emoji for the guild. Requires the `CREATE_GUILD_EXPRESSIONS` permission. Returns the new [emoji](/developers/resources/emoji#emoji-object) object on success. Fires a [Guild Emojis Update](/developers/events/gateway-events#guild-emojis-update) Gateway event.

<Warning>
  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).
</Warning>

<Info>
  We highly recommend that developers use the `.webp` extension when fetching emoji 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.
</Info>

<Info>
  This endpoint supports the `X-Audit-Log-Reason` header.
</Info>

<ManualAnchor id="create-guild-emoji-json-params" />

###### JSON Params

| Field | Type                                           | Description                     |
| ----- | ---------------------------------------------- | ------------------------------- |
| name  | string                                         | name of the emoji               |
| image | [image data](/developers/reference#image-data) | the 128x128 emoji image         |
| roles | array of snowflakes                            | roles allowed to use this emoji |

## Modify Guild Emoji

<Route method="PATCH">/guilds/[\{guild.id}](/developers/resources/guild#guild-object)/emojis/[\{emoji.id}](/developers/resources/emoji#emoji-object)</Route>

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](/developers/resources/emoji#emoji-object) object on success. Fires a [Guild Emojis Update](/developers/events/gateway-events#guild-emojis-update) Gateway event.

<Note>
  All parameters to this endpoint are optional.
</Note>

<Info>
  This endpoint supports the `X-Audit-Log-Reason` header.
</Info>

<ManualAnchor id="modify-guild-emoji-json-params" />

###### JSON Params

| Field | Type                 | Description                     |
| ----- | -------------------- | ------------------------------- |
| name  | string               | name of the emoji               |
| roles | ?array of snowflakes | roles allowed to use this emoji |

## Delete Guild Emoji

<Route method="DELETE">/guilds/[\{guild.id}](/developers/resources/guild#guild-object)/emojis/[\{emoji.id}](/developers/resources/emoji#emoji-object)</Route>

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](/developers/events/gateway-events#guild-emojis-update) Gateway event.

<Info>
  This endpoint supports the `X-Audit-Log-Reason` header.
</Info>

## List Application Emojis

<Route method="GET">/applications/[\{application.id}](/developers/resources/application#application-object)/emojis</Route>

Returns an object containing a list of [emoji](/developers/resources/emoji#emoji-object) objects for the given application under the `items` key. Includes a `user` object for the team member that uploaded the emoji from the app's settings, or for the bot user if uploaded using the API.

```json theme={null}
{
  "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

<Route method="GET">/applications/[\{application.id}](/developers/resources/application#application-object)/emojis/[\{emoji.id}](/developers/resources/emoji#emoji-object)</Route>

Returns an [emoji](/developers/resources/emoji#emoji-object) object for the given application and emoji IDs. Includes the `user` field.

## Create Application Emoji

<Route method="POST">/applications/[\{application.id}](/developers/resources/application#application-object)/emojis</Route>

Create a new emoji for the application. Returns the new [emoji](/developers/resources/emoji#emoji-object) object on success.

<Warning>
  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).
</Warning>

<Info>
  We highly recommend that developers use the `.webp` extension when fetching emoji 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.
</Info>

<ManualAnchor id="create-application-emoji-json-params" />

###### JSON Params

| Field | Type                                           | Description             |
| ----- | ---------------------------------------------- | ----------------------- |
| name  | string                                         | name of the emoji       |
| image | [image data](/developers/reference#image-data) | the 128x128 emoji image |

## Modify Application Emoji

<Route method="PATCH">/applications/[\{application.id}](/developers/resources/application#application-object)/emojis/[\{emoji.id}](/developers/resources/emoji#emoji-object)</Route>

Modify the given emoji. Returns the updated [emoji](/developers/resources/emoji#emoji-object) object on success.

<ManualAnchor id="modify-application-emoji-json-params" />

###### JSON Params

| Field | Type   | Description       |
| ----- | ------ | ----------------- |
| name  | string | name of the emoji |

## Delete Application Emoji

<Route method="DELETE">/applications/[\{application.id}](/developers/resources/application#application-object)/emojis/[\{emoji.id}](/developers/resources/emoji#emoji-object)</Route>

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