From 091aad189b74d4cbfa31cbb291652e240072e618 Mon Sep 17 00:00:00 2001 From: Scott Kidder Date: Tue, 20 May 2025 18:03:17 -0700 Subject: [PATCH 1/7] [docs] Document WebP support for emoji requests Fixes #7567 - Add information about supported emoji upload formats - Explain that all emoji formats can be served as WebP - Recommend WebP for maximum performance and compatibility - Document how to request still and animated WebP emojis --- docs/resources/emoji.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/resources/emoji.mdx b/docs/resources/emoji.mdx index 886dd112c6..1ec126ece3 100644 --- a/docs/resources/emoji.mdx +++ b/docs/resources/emoji.mdx @@ -30,6 +30,12 @@ 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. +###### 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 request emojis as WebP for maximum performance and compatibility. The Discord client uses WebP for all emojis displayed in-app. + +Still 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 Emoji An application can own up to 2000 emojis that can only be used by that app. @@ -110,6 +116,10 @@ Create a new emoji for the guild. Requires the `CREATE_GUILD_EXPRESSIONS` permis 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](/docs/topics/opcodes-and-status-codes#json). ::: +:::info +We highly recommend requesting emojis as WebP for maximum performance and compatibility. See [Emoji Formats](#emoji-formats) for more details. +::: + :::info This endpoint supports the `X-Audit-Log-Reason` header. ::: @@ -192,6 +202,10 @@ Create a new emoji for the application. Returns the new [emoji](/docs/resources/ 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](/docs/topics/opcodes-and-status-codes#json). ::: +:::info +We highly recommend requesting emojis as WebP for maximum performance and compatibility. See [Emoji Formats](#emoji-formats) for more details. +::: + ###### JSON Params | Field | Type | Description | From 915e9123fa37797d85d99eeb485a7e2a0eee7039 Mon Sep 17 00:00:00 2001 From: Scott Kidder Date: Tue, 20 May 2025 18:15:07 -0700 Subject: [PATCH 2/7] [docs] Fix links to Emoji Formats section --- docs/resources/emoji.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/resources/emoji.mdx b/docs/resources/emoji.mdx index 1ec126ece3..312bfd28a0 100644 --- a/docs/resources/emoji.mdx +++ b/docs/resources/emoji.mdx @@ -117,7 +117,7 @@ Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to up ::: :::info -We highly recommend requesting emojis as WebP for maximum performance and compatibility. See [Emoji Formats](#emoji-formats) for more details. +We highly recommend requesting emojis as WebP for maximum performance and compatibility. See the Emoji Formats section above for more details. ::: :::info @@ -203,7 +203,7 @@ Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to up ::: :::info -We highly recommend requesting emojis as WebP for maximum performance and compatibility. See [Emoji Formats](#emoji-formats) for more details. +We highly recommend requesting emojis as WebP for maximum performance and compatibility. See the Emoji Formats section above for more details. ::: ###### JSON Params From 9bd5d0ce727fb4026a73bda96f04c79890847cec Mon Sep 17 00:00:00 2001 From: Scott Kidder Date: Tue, 20 May 2025 18:34:30 -0700 Subject: [PATCH 3/7] [docs] Update reference documentation for emoji formats - Add AVIF to supported image formats - Add AVIF to supported Custom Emoji formats - Include emoji format information and WebP recommendations in footnotes --- docs/reference.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/reference.mdx b/docs/reference.mdx index c451adbf47..78c3f412e1 100644 --- a/docs/reference.mdx +++ b/docs/reference.mdx @@ -325,13 +325,14 @@ Discord uses ids and hashes to render images in the client. These hashes can be | PNG | .png | | WebP | .webp | | GIF | .gif | +| AVIF | .avif | | Lottie | .json | ###### CDN Endpoints | Type | Path | Supports | |-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------| -| Custom Emoji | emojis/[emoji_id](/docs/resources/emoji#emoji-object).png | PNG, JPEG, WebP, GIF | +| Custom Emoji | emojis/[emoji_id](/docs/resources/emoji#emoji-object).png \*\*\*\*\* | PNG, JPEG, WebP, GIF, AVIF | | Guild Icon | icons/[guild_id](/docs/resources/guild#guild-object)/[guild_icon](/docs/resources/guild#guild-object).png \* | PNG, JPEG, WebP, GIF | | Guild Splash | splashes/[guild_id](/docs/resources/guild#guild-object)/[guild_splash](/docs/resources/guild#guild-object).png | PNG, JPEG, WebP | | Guild Discovery Splash | discovery-splashes/[guild_id](/docs/resources/guild#guild-object)/[guild_discovery_splash](/docs/resources/guild#guild-object).png | PNG, JPEG, WebP | @@ -361,6 +362,8 @@ Discord uses ids and hashes to render images in the client. These hashes can be \*\*\*\* In the case of the Sticker endpoint, the sticker will be available as PNG if its [`format_type`](/docs/resources/sticker#sticker-object) is `PNG` or `APNG`, GIF if its `format_type` is `GIF`, and as [Lottie](https://airbnb.io/lottie/#/) if its `format_type` is `LOTTIE`. +\*\*\*\*\* For Custom Emoji, we highly recommend requesting emojis as WebP for maximum performance and compatibility. Emojis can be uploaded as JPEG, PNG, GIF, WebP, and AVIF formats. WebP and AVIF formats must be requested as WebP since they don't convert well to other formats. The Discord client uses WebP for all emojis displayed in-app. See the [Emoji Resource](/docs/resources/emoji) page for more details. + :::info Sticker GIFs do not use the CDN base url, and can be accessed at `https://media.discordapp.net/stickers/.gif`. ::: From d81037939ffa95bce711a32e5ce1b7daa43293c9 Mon Sep 17 00:00:00 2001 From: Scott Kidder Date: Tue, 20 May 2025 20:26:25 -0700 Subject: [PATCH 4/7] [docs] Fix markdown table formatting --- docs/reference.mdx | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/reference.mdx b/docs/reference.mdx index 78c3f412e1..0d7503e6b9 100644 --- a/docs/reference.mdx +++ b/docs/reference.mdx @@ -330,29 +330,29 @@ Discord uses ids and hashes to render images in the client. These hashes can be ###### CDN Endpoints -| Type | Path | Supports | -|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------| -| Custom Emoji | emojis/[emoji_id](/docs/resources/emoji#emoji-object).png \*\*\*\*\* | PNG, JPEG, WebP, GIF, AVIF | -| Guild Icon | icons/[guild_id](/docs/resources/guild#guild-object)/[guild_icon](/docs/resources/guild#guild-object).png \* | PNG, JPEG, WebP, GIF | -| Guild Splash | splashes/[guild_id](/docs/resources/guild#guild-object)/[guild_splash](/docs/resources/guild#guild-object).png | PNG, JPEG, WebP | -| Guild Discovery Splash | discovery-splashes/[guild_id](/docs/resources/guild#guild-object)/[guild_discovery_splash](/docs/resources/guild#guild-object).png | PNG, JPEG, WebP | -| Guild Banner | banners/[guild_id](/docs/resources/guild#guild-object)/[guild_banner](/docs/resources/guild#guild-object).png \* | PNG, JPEG, WebP, GIF | -| User Banner | banners/[user_id](/docs/resources/user#user-object)/[user_banner](/docs/resources/user#user-object).png \* | PNG, JPEG, WebP, GIF | -| Default User Avatar | embed/avatars/[index](/docs/resources/user#user-object).png \*\* \*\*\* | PNG | -| User Avatar | avatars/[user_id](/docs/resources/user#user-object)/[user_avatar](/docs/resources/user#user-object).png \* | PNG, JPEG, WebP, GIF | -| Guild Member Avatar | guilds/[guild_id](/docs/resources/guild#guild-object)/users/[user_id](/docs/resources/user#user-object)/avatars/[member_avatar](/docs/resources/guild#guild-member-object).png \* | PNG, JPEG, WebP, GIF | -| Avatar Decoration | avatar-decoration-presets/[avatar_decoration_data_asset](/docs/resources/user#avatar-decoration-data-object).png | PNG | -| Application Icon | app-icons/[application_id](/docs/resources/application#application-object)/[icon](/docs/resources/application#application-object).png | PNG, JPEG, WebP | -| Application Cover | app-icons/[application_id](/docs/resources/application#application-object)/[cover_image](/docs/resources/application#application-object).png | PNG, JPEG, WebP | -| Application Asset | app-assets/[application_id](/docs/resources/application#application-object)/[asset_id](/docs/events/gateway-events#activity-object-activity-assets).png | PNG, JPEG, WebP | -| Achievement Icon | app-assets/[application_id](/docs/resources/application#application-object)/achievements/[achievement_id](https://github.com/discord/discord-api-docs/blob/legacy-gamesdk/docs/game_sdk/Achievements.md#user-achievement-struct)/icons/[icon_hash](https://github.com/discord/discord-api-docs/blob/legacy-gamesdk/docs/game_sdk/Achievements.md#user-achievement-struct).png | PNG, JPEG, WebP | -| Store Page Asset | app-assets/[application_id](/docs/resources/application#application-object)/store/asset_id | PNG, JPEG, WebP | -| Sticker Pack Banner | app-assets/710982414301790216/store/[sticker_pack_banner_asset_id](/docs/resources/sticker#sticker-pack-object).png | PNG, JPEG, WebP | -| Team Icon | team-icons/[team_id](/docs/topics/teams#data-models-team-object)/[team_icon](/docs/topics/teams#data-models-team-object).png | PNG, JPEG, WebP | -| Sticker | stickers/[sticker_id](/docs/resources/sticker#sticker-object).png \*\*\* \*\*\*\* | PNG, Lottie, GIF | -| Role Icon | role-icons/[role_id](/docs/topics/permissions#role-object)/[role_icon](/docs/topics/permissions#role-object).png | PNG, JPEG, WebP | -| Guild Scheduled Event Cover | guild-events/[scheduled_event_id](/docs/resources/guild-scheduled-event#guild-scheduled-event-object)/[scheduled_event_cover_image](/docs/resources/guild-scheduled-event#guild-scheduled-event-object).png | PNG, JPEG, WebP | -| Guild Member Banner | guilds/[guild_id](/docs/resources/guild#guild-object)/users/[user_id](/docs/resources/user#user-object)/banners/[member_banner](/docs/resources/guild#guild-member-object).png \* | PNG, JPEG, WebP, GIF | +| Type | Path | Supports | +|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| Custom Emoji | emojis/[emoji_id](/docs/resources/emoji#emoji-object).png \*\*\*\*\* | PNG, JPEG, WebP, GIF, AVIF | +| Guild Icon | icons/[guild_id](/docs/resources/guild#guild-object)/[guild_icon](/docs/resources/guild#guild-object).png \* | PNG, JPEG, WebP, GIF | +| Guild Splash | splashes/[guild_id](/docs/resources/guild#guild-object)/[guild_splash](/docs/resources/guild#guild-object).png | PNG, JPEG, WebP | +| Guild Discovery Splash | discovery-splashes/[guild_id](/docs/resources/guild#guild-object)/[guild_discovery_splash](/docs/resources/guild#guild-object).png | PNG, JPEG, WebP | +| Guild Banner | banners/[guild_id](/docs/resources/guild#guild-object)/[guild_banner](/docs/resources/guild#guild-object).png \* | PNG, JPEG, WebP, GIF | +| User Banner | banners/[user_id](/docs/resources/user#user-object)/[user_banner](/docs/resources/user#user-object).png \* | PNG, JPEG, WebP, GIF | +| Default User Avatar | embed/avatars/[index](/docs/resources/user#user-object).png \*\* \*\*\* | PNG | +| User Avatar | avatars/[user_id](/docs/resources/user#user-object)/[user_avatar](/docs/resources/user#user-object).png \* | PNG, JPEG, WebP, GIF | +| Guild Member Avatar | guilds/[guild_id](/docs/resources/guild#guild-object)/users/[user_id](/docs/resources/user#user-object)/avatars/[member_avatar](/docs/resources/guild#guild-member-object).png \* | PNG, JPEG, WebP, GIF | +| Avatar Decoration | avatar-decoration-presets/[avatar_decoration_data_asset](/docs/resources/user#avatar-decoration-data-object).png | PNG | +| Application Icon | app-icons/[application_id](/docs/resources/application#application-object)/[icon](/docs/resources/application#application-object).png | PNG, JPEG, WebP | +| Application Cover | app-icons/[application_id](/docs/resources/application#application-object)/[cover_image](/docs/resources/application#application-object).png | PNG, JPEG, WebP | +| Application Asset | app-assets/[application_id](/docs/resources/application#application-object)/[asset_id](/docs/events/gateway-events#activity-object-activity-assets).png | PNG, JPEG, WebP | +| Achievement Icon | app-assets/[application_id](/docs/resources/application#application-object)/achievements/[achievement_id](https://github.com/discord/discord-api-docs/blob/legacy-gamesdk/docs/game_sdk/Achievements.md#user-achievement-struct)/icons/[icon_hash](https://github.com/discord/discord-api-docs/blob/legacy-gamesdk/docs/game_sdk/Achievements.md#user-achievement-struct).png | PNG, JPEG, WebP | +| Store Page Asset | app-assets/[application_id](/docs/resources/application#application-object)/store/asset_id | PNG, JPEG, WebP | +| Sticker Pack Banner | app-assets/710982414301790216/store/[sticker_pack_banner_asset_id](/docs/resources/sticker#sticker-pack-object).png | PNG, JPEG, WebP | +| Team Icon | team-icons/[team_id](/docs/topics/teams#data-models-team-object)/[team_icon](/docs/topics/teams#data-models-team-object).png | PNG, JPEG, WebP | +| Sticker | stickers/[sticker_id](/docs/resources/sticker#sticker-object).png \*\*\* \*\*\*\* | PNG, Lottie, GIF | +| Role Icon | role-icons/[role_id](/docs/topics/permissions#role-object)/[role_icon](/docs/topics/permissions#role-object).png | PNG, JPEG, WebP | +| Guild Scheduled Event Cover | guild-events/[scheduled_event_id](/docs/resources/guild-scheduled-event#guild-scheduled-event-object)/[scheduled_event_cover_image](/docs/resources/guild-scheduled-event#guild-scheduled-event-object).png | PNG, JPEG, WebP | +| Guild Member Banner | guilds/[guild_id](/docs/resources/guild#guild-object)/users/[user_id](/docs/resources/user#user-object)/banners/[member_banner](/docs/resources/guild#guild-member-object).png \* | PNG, JPEG, WebP, GIF | \* In the case of endpoints that support GIFs, the hash will begin with `a_` if it is available in GIF format. These images can also be retrieved as animated WebP using the `?animated=true` querystring parameter. (example: `a_1269e74af4df7417b13759eae50c83dc`) From 4a0579cbec1120d7879544a9e3692b862c8c2ea6 Mon Sep 17 00:00:00 2001 From: Scott Kidder Date: Thu, 22 May 2025 10:21:52 -0700 Subject: [PATCH 5/7] Update docs/resources/emoji.mdx Co-authored-by: Mark Mandel --- docs/resources/emoji.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources/emoji.mdx b/docs/resources/emoji.mdx index 312bfd28a0..57a799dc61 100644 --- a/docs/resources/emoji.mdx +++ b/docs/resources/emoji.mdx @@ -203,7 +203,7 @@ Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to up ::: :::info -We highly recommend requesting emojis as WebP for maximum performance and compatibility. See the Emoji Formats section above for more details. +We highly recommend requesting emojis as WebP for maximum performance and compatibility. See the [Emoji Formats](#emoji-object-emoji-formats) section above for more details. ::: ###### JSON Params From f9c249e325e745349ab0506163171c2fe2fb2535 Mon Sep 17 00:00:00 2001 From: Scott Kidder Date: Thu, 22 May 2025 10:28:29 -0700 Subject: [PATCH 6/7] [docs] Improve emoji WebP format documentation clarity --- docs/resources/emoji.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/resources/emoji.mdx b/docs/resources/emoji.mdx index 57a799dc61..6616f00ab6 100644 --- a/docs/resources/emoji.mdx +++ b/docs/resources/emoji.mdx @@ -32,9 +32,9 @@ 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 request emojis as WebP for maximum performance and compatibility. The Discord client uses WebP for all emojis displayed in-app. +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 emojis can be requested using the `.webp` file extension. For animated WebP emojis, use the `.webp` extension with the `?animated=true` query parameter. +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. ###### Application-Owned Emoji @@ -117,7 +117,7 @@ Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to up ::: :::info -We highly recommend requesting emojis as WebP for maximum performance and compatibility. See the Emoji Formats section above for more details. +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](#emoji-object-emoji-formats) section above for more details. ::: :::info @@ -203,7 +203,7 @@ Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to up ::: :::info -We highly recommend requesting emojis as WebP for maximum performance and compatibility. See the [Emoji Formats](#emoji-object-emoji-formats) section above for more details. +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](#emoji-object-emoji-formats) section above for more details. ::: ###### JSON Params From 52878b01dbcdaadd2caf38734ee227b0947b9ae7 Mon Sep 17 00:00:00 2001 From: Scott Kidder Date: Thu, 22 May 2025 10:39:32 -0700 Subject: [PATCH 7/7] [docs] Fix anchor links to Emoji Formats section --- docs/resources/emoji.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/resources/emoji.mdx b/docs/resources/emoji.mdx index 6616f00ab6..f69fe6ce62 100644 --- a/docs/resources/emoji.mdx +++ b/docs/resources/emoji.mdx @@ -117,7 +117,7 @@ Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to up ::: :::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](#emoji-object-emoji-formats) section above for more details. +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](/docs/resources/emoji#emoji-object-emoji-formats) section above for more details. ::: :::info @@ -203,7 +203,7 @@ Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to up ::: :::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](#emoji-object-emoji-formats) section above for more details. +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](/docs/resources/emoji#emoji-object-emoji-formats) section above for more details. ::: ###### JSON Params