Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document sticker packs, sticker routes, and guild stickers #3128

Merged
merged 26 commits into from
Jul 19, 2021
Merged

Document sticker packs, sticker routes, and guild stickers #3128

Show file tree
Hide file tree
Changes from 18 commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
fccd6f0
Document sticker packs and sticker routes
advaith1 Jun 16, 2021
7289094
update sort_value desc
advaith1 Jun 16, 2021
8a170c9
fix header
advaith1 Jun 16, 2021
147f8c0
Document guild.stickers
advaith1 Jun 16, 2021
0b7f14d
Document create, modify, and delete routes
advaith1 Jun 16, 2021
e17f6fe
Document /stickers/:id
advaith1 Jun 18, 2021
57e9b57
document that manage_emojis controls stickers too
advaith1 Jun 23, 2021
db5a0cc
fix req'd permission and update name
advaith1 Jun 25, 2021
e5863b3
mark cover_sticker_id as optional
advaith1 Jun 25, 2021
c78e881
Document Guild Stickers Update gateway event
advaith1 Jul 2, 2021
8fce653
Merge branch 'master' into sticker-packs
advaith1 Jul 2, 2021
ce4848a
add sticker item object to sticker file
advaith1 Jul 2, 2021
ab75fcb
Document sending sticker_ids
advaith1 Jul 2, 2021
27fffb6
description is nullable, update endpoint docs, add error codes
advaith1 Jul 2, 2021
6ebab4a
update sticker.available description
advaith1 Jul 2, 2021
c0070a6
add sticker audit log events and change keys
advaith1 Jul 2, 2021
d294da3
document that tags is the Discord name
advaith1 Jul 2, 2021
e2b3d77
Document the sticker CDN endpoint
advaith1 Jul 3, 2021
2af8851
update sticker.available desc x2
advaith1 Jul 3, 2021
c54291b
add error 170005
advaith1 Jul 7, 2021
03626e1
Add USE_EXTERNAL_STICKERS permission
advaith1 Jul 16, 2021
9f0219e
Merge remote-tracking branch 'upstream/master' into sticker-packs
advaith1 Jul 17, 2021
8113d3d
Merge branch 'master' into sticker-packs
advaith1 Jul 17, 2021
fb59f04
audit log reason header
advaith1 Jul 17, 2021
a02d435
add error code 170007
advaith1 Jul 17, 2021
7262260
add other sticker errors
advaith1 Jul 19, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
19 changes: 12 additions & 7 deletions docs/Reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,12 +278,13 @@ Discord uses ids and hashes to render images in the client. These hashes can be

###### Image Formats

| Name | Extension |
|------|-------------|
| JPEG | .jpg, .jpeg |
| PNG | .png |
| WebP | .webp |
| GIF | .gif |
| Name | Extension |
|--------|-------------|
| JPEG | .jpg, .jpeg |
| PNG | .png |
| WebP | .webp |
| GIF | .gif |
| Lottie | .json |

###### CDN Endpoints

Expand All @@ -300,13 +301,17 @@ Discord uses ids and hashes to render images in the client. These hashes can be
| 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_TOPICS_GATEWAY/activity-object-activity-assets).png | PNG, JPEG, WebP |
| Achievement Icon | app-assets/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/achievements/[achievement_id](#DOCS_GAME_SDK_ACHIEVEMENTS/data-models-user-achievement-struct)/icons/[icon_hash](#DOCS_GAME_SDK_ACHIEVEMENTS/data-models-user-achievement-struct).png | 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 |
advaith1 marked this conversation as resolved.
Show resolved Hide resolved
| Team Icon | team-icons/[team_id](#DOCS_TOPICS_TEAMS/team-object)/[team_icon](#DOCS_TOPICS_TEAMS/team-object).png | PNG, JPEG, WebP |
| Sticker | stickers/[sticker_id](#DOCS_RESOURCES_STICKER/sticker-object).png \*\*\* \*\*\*\* | PNG, Lottie |

\* In the case of endpoints that support GIFs, the hash will begin with `a_` if it is available in GIF format. (example: `a_1269e74af4df7417b13759eae50c83dc`)

\*\* In the case of the Default User Avatar endpoint, the value for `user_discriminator` in the path should be the user's discriminator modulo 5—Test#1337 would be `1337 % 5`, which evaluates to 2.

\*\*\* In the case of the Default User Avatar endpoint, the size of images returned is constant with the "size" querystring parameter being ignored.
\*\*\* In the case of the Default User Avatar and Sticker endpoints, the size of images returned is constant with the "size" querystring parameter being ignored.

\*\*\*\* 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`, and as [Lottie](https://airbnb.io/lottie/#/) if its `format_type` is `LOTTIE`.

## Image Data

Expand Down
122 changes: 65 additions & 57 deletions docs/resources/Audit_Log.md
View file
Open in desktop

Large diffs are not rendered by default.

70 changes: 16 additions & 54 deletions docs/resources/Channel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,11 +263,11 @@ Represents a message sent in a channel within Discord.
| message_reference? | [message reference](#DOCS_RESOURCES_CHANNEL/message-reference-object-message-reference-structure) object | data showing the source of a crosspost, channel follow add, pin, or reply message |
| flags? | integer | [message flags](#DOCS_RESOURCES_CHANNEL/message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) |
| referenced_message?\*\*\*\*\* | ?[message object](#DOCS_RESOURCES_CHANNEL/message-object) | the message associated with the message_reference |
| interaction? | [message interaction object](#DOCS_INTERACTIONS_SLASH_COMMANDS/message-interaction-object-message-interaction-structure) | sent if the message is a response to an [Interaction](#DOCS_INTERACTIONS_SLASH_COMMANDS/) |
| interaction? | [message interaction object](#DOCS_INTERACTIONS_SLASH_COMMANDS/message-interaction-object-message-interaction-structure) | sent if the message is a response to an [Interaction](#DOCS_INTERACTIONS_SLASH_COMMANDS/) |
| thread? | [channel](#DOCS_RESOURCES_CHANNEL/channel) object | the thread that was started from this message, includes [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object |
| components? | Array of [message components](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/component-object) | sent if the message contains components like buttons, action rows, or other interactive components |
| sticker_items?\*\*\*\*\*\* | array of [message sticker item objects](#DOCS_RESOURCES_CHANNEL/message-object-message-sticker-item-structure) | sent if the message contains stickers |
| stickers? | array of [sticker](#DOCS_RESOURCES_CHANNEL/message-object-message-sticker-structure) objects | **Deprecated** the stickers sent with the message |
| components? | Array of [message components](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/component-object) | sent if the message contains components like buttons, action rows, or other interactive components |
| sticker_items? | array of [message sticker item objects](#DOCS_RESOURCES_STICKER/sticker-item-object) | sent if the message contains stickers |
| stickers? | array of [sticker](#DOCS_RESOURCES_STICKER/sticker-object) objects | **Deprecated** the stickers sent with the message |

\* The author object follows the structure of the user object, but is only a valid user in the case where the message is generated by a user or bot user. If the message is generated by a webhook, the author object corresponds to the webhook's id, username, and avatar. You can tell if a message is generated by a webhook by checking for the `webhook_id` on the message object.

Expand All @@ -279,8 +279,6 @@ Represents a message sent in a channel within Discord.

\*\*\*\*\* This field is only returned for messages with a `type` of `19` (REPLY) or `21` (THREAD_STARTER_MESSAGE). If the message is a reply but the `referenced_message` field is not present, the backend did not attempt to fetch the message that was being replied to, so its state is unknown. If the field exists but is null, the referenced message was deleted.

\*\*\*\*\*\* Bots cannot send stickers.

###### Message Types

> warn
Expand Down Expand Up @@ -340,43 +338,6 @@ Represents a message sent in a channel within Discord.
| EPHEMERAL | 1 << 6 | this message is only visible to the user who invoked the Interaction |
| LOADING | 1 << 7 | this message is an Interaction Response and the bot is "thinking" |

###### Message Sticker Item Structure

The smallest amount of data required to render a sticker.

| Field | Type | Description |
| ---------------- | --------- | --------------------------------------------------------------------------------------------- |
| id | snowflake | id of the sticker |
| name | string | name of the sticker |
| format_type | integer | [type of sticker format](#DOCS_RESOURCES_CHANNEL/message-object-message-sticker-format-types) |

###### Message Sticker Format Types

| Type | Value |
| ------ | ----- |
| PNG | 1 |
| APNG | 2 |
| LOTTIE | 3 |


###### Message Sticker Structure

| Field | Type | Description |
| ---------------- | --------- | --------------------------------------------------------------------------------------------- |
| id | snowflake | id of the sticker |
| pack_id? | snowflake | id of the pack the sticker is from |
| name | string | name of the sticker |
| description | string | description of the sticker |
| tags | string | for guild stickers, a unicode emoji representing the sticker's expression. for nitro stickers, a comma-separated list of related expressions. |
| asset\* | string | **Deprecated** previously the sticker asset hash, now an empty string |
| format_type | integer | [type of sticker format](#DOCS_RESOURCES_CHANNEL/message-object-message-sticker-format-types) |
| available? | boolean | whether or not the sticker is available |
| guild_id? | snowflake | id of the guild that owns this sticker |
| user? | [user](#DOCS_RESOURCES_USER/user-object) object | the user that uploaded the sticker |
| sort_value? | integer | a sticker's sort order within a pack |

\* The URL for fetching sticker assets is currently private.

###### Example Message

```json
Expand Down Expand Up @@ -921,17 +882,18 @@ You may create a message as a reply to another message. To do so, include a [`me

###### JSON/Form Params

| Field | Type | Description | Required |
| -------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------- |
| content | string | the message contents (up to 2000 characters) | one of content, file, embeds |
| tts | boolean | true if this is a TTS message | false |
| file | file contents | the contents of the file being sent | one of content, file, embeds |
| embeds | array of [embed](#DOCS_RESOURCES_CHANNEL/embed-object) objects | embedded `rich` content (up to 6000 characters) | one of content, file, embeds |
| embed *(deprecated)* | [embed](#DOCS_RESOURCES_CHANNEL/embed-object) object | embedded `rich` content, deprecated in favor of `embeds` | one of content, file, embed |
| payload_json | string | JSON encoded body of non-file params | `multipart/form-data` only |
| allowed_mentions | [allowed mention object](#DOCS_RESOURCES_CHANNEL/allowed-mentions-object) | allowed mentions for the message | false |
| message_reference | [message reference](#DOCS_RESOURCES_CHANNEL/message-reference-object-message-reference-structure) | include to make your message a reply | false |
| components | array of [message component](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/component-object) objects | the components to include with the message | false |
| Field | Type | Description | Required |
| -------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
| content | string | the message contents (up to 2000 characters) | one of content, file, embed(s), sticker_ids |
| tts | boolean | true if this is a TTS message | false |
| file | file contents | the contents of the file being sent | one of content, file, embed(s), sticker_ids |
| embeds | array of [embed](#DOCS_RESOURCES_CHANNEL/embed-object) objects | embedded `rich` content (up to 6000 characters) | one of content, file, embed(s), sticker_ids |
| embed *(deprecated)* | [embed](#DOCS_RESOURCES_CHANNEL/embed-object) object | embedded `rich` content, deprecated in favor of `embeds` | one of content, file, embed(s), sticker_ids |
| payload_json | string | JSON encoded body of non-file params | `multipart/form-data` only |
| allowed_mentions | [allowed mention object](#DOCS_RESOURCES_CHANNEL/allowed-mentions-object) | allowed mentions for the message | false |
| message_reference | [message reference](#DOCS_RESOURCES_CHANNEL/message-reference-object-message-reference-structure) | include to make your message a reply | false |
| components | array of [message component](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/component-object) objects | the components to include with the message | false |
| sticker_ids | array of snowflakes | IDs of up to 3 [stickers](#DOCS_RESOURCES_STICKER/sticker-object) in the server to send in the message | one of content, file, embed(s), sticker_ids |

###### Example Request Body (application/json)

Expand Down
6 changes: 3 additions & 3 deletions docs/resources/Emoji.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ Returns an [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object for the given guil

## Create Guild Emoji % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/emojis

Create a new emoji for the guild. Requires the `MANAGE_EMOJIS` permission. Returns the new [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY/guild-emojis-update) Gateway event.
Create a new emoji for the guild. Requires the `MANAGE_EMOJIS_AND_STICKERS` permission. Returns the new [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY/guild-emojis-update) Gateway event.

> warn
> Emojis and animated emojis have a maximum file size of 256kb. 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).
Expand All @@ -96,7 +96,7 @@ Create a new emoji for the guild. Requires the `MANAGE_EMOJIS` permission. Retur

## Modify Guild Emoji % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/emojis/{emoji.id#DOCS_RESOURCES_EMOJI/emoji-object}

Modify the given emoji. Requires the `MANAGE_EMOJIS` permission. Returns the updated [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY/guild-emojis-update) Gateway event.
Modify the given emoji. Requires the `MANAGE_EMOJIS_AND_STICKERS` permission. Returns the updated [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY/guild-emojis-update) Gateway event.

> info
> All parameters to this endpoint are optional.
Expand All @@ -110,4 +110,4 @@ Modify the given emoji. Requires the `MANAGE_EMOJIS` permission. Returns the upd

## Delete Guild Emoji % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/emojis/{emoji.id#DOCS_RESOURCES_EMOJI/emoji-object}

Delete the given emoji. Requires the `MANAGE_EMOJIS` permission. Returns `204 No Content` on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY/guild-emojis-update) Gateway event.
Delete the given emoji. Requires the `MANAGE_EMOJIS_AND_STICKERS` permission. Returns `204 No Content` on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY/guild-emojis-update) Gateway event.