diff --git a/docs/Change_Log.md b/docs/Change_Log.md index e9113b04a1..54cdb3a880 100644 --- a/docs/Change_Log.md +++ b/docs/Change_Log.md @@ -1,5 +1,11 @@ # Change Log +## Forum Channels + +#### Apr 06, 2022 + +Added new channel type, `GUILD_FORUM` (15). A `GUILD_FORUM` channel is an unreleased feature that is very similar (from an API perspective) to a `GUILD_TEXT` channel, except only threads can be created in that channel; messages cannot be sent directly in that channel. Check out the [forums topic](#DOCS_TOPICS_THREADS/forums) for more information. + ## Guild Bans Pagination #### Mar 31, 2022 diff --git a/docs/resources/Channel.md b/docs/resources/Channel.md index b094d8ef6f..6fb5d62ea7 100644 --- a/docs/resources/Channel.md +++ b/docs/resources/Channel.md @@ -16,7 +16,7 @@ Represents a guild or DM channel within Discord. | name? | ?string | the name of the channel (1-100 characters) | | topic? | ?string | the channel topic (0-1024 characters) | | nsfw? | boolean | whether the channel is nsfw | -| last_message_id? | ?snowflake | the id of the last message sent in this channel (may not point to an existing or valid message) | +| last_message_id? | ?snowflake | the id of the last message sent in this channel (or thread for `GUILD_FORUM` channels) (may not point to an existing or valid message or thread) | | bitrate? | integer | the bitrate (in bits) of the voice channel | | user_limit? | integer | the user limit of the voice channel | | rate_limit_per_user?\* | integer | amount of seconds a user has to wait before sending another message (0-21600); bots, as well as users with the permission `manage_messages` or `manage_channel`, are unaffected | @@ -34,6 +34,7 @@ Represents a guild or DM channel within Discord. | member? | a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object | thread member object for the current user, if they have joined the thread, only included on certain API endpoints | | default_auto_archive_duration? | integer | default duration that the clients (not the API) will use for newly created threads, in minutes, to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080 | | permissions? | string | computed permissions for the invoking user in the channel, including overwrites, only included when part of the `resolved` data received on a slash command interaction | +| flags? | integer | [channel flags](#DOCS_RESOURCES_CHANNEL/channel-object-channel-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) | \* `rate_limit_per_user` also applies to thread creation. Users can send one message and create one thread during each `rate_limit_per_user` interval. @@ -54,7 +55,10 @@ Represents a guild or DM channel within Discord. | GUILD_PUBLIC_THREAD | 11 | a temporary sub-channel within a GUILD_TEXT channel | | GUILD_PRIVATE_THREAD | 12 | a temporary sub-channel within a GUILD_TEXT channel that is only viewable by those invited and those with the MANAGE_THREADS permission | | GUILD_STAGE_VOICE | 13 | a voice channel for [hosting events with an audience](https://support.discord.com/hc/en-us/articles/1500005513722) | -| GUILD_DIRECTORY | 14 | the channel in a [hub](https://support.discord.com/hc/en-us/articles/4406046651927-Discord-Student-Hubs-FAQ) containing the listed servers | +| GUILD_DIRECTORY | 14 | the channel in a [hub](https://support.discord.com/hc/en-us/articles/4406046651927-Discord-Student-Hubs-FAQ) containing the listed servers | +| GUILD_FORUM\* | 15 | (still in development) a channel that can only contain threads | + +\* The `GUILD_FORUM` channel type is still in active development. Avoid implementing any features that are not documented here, since they are subject to change without notice! ###### Video Quality Modes @@ -63,6 +67,12 @@ Represents a guild or DM channel within Discord. | AUTO | 1 | Discord chooses the quality for optimal performance | | FULL | 2 | 720p | +###### Channel Flags + +| Flag | Value | Description | +|----------------------------------------|--------|-----------------------------------------------------------------------------------| +| PINNED | 1 << 1 | this thread is pinned to the top of its parent forum channel | + ###### Example Guild Text Channel ```json @@ -1109,11 +1119,11 @@ Adds a recipient to a Group DM using their access token. Removes a recipient from a Group DM. -## Start Thread with Message % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_CHANNEL/message-object}/threads +## Start Thread from Message % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_CHANNEL/message-object}/threads Creates a new thread from an existing message. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) on success, and a 400 BAD REQUEST on invalid parameters. Fires a [Thread Create](#DOCS_TOPICS_GATEWAY/thread-create) Gateway event. -When called on a `GUILD_TEXT` channel, creates a `GUILD_PUBLIC_THREAD`. When called on a `GUILD_NEWS` channel, creates a `GUILD_NEWS_THREAD`. The id of the created thread will be the same as the id of the message, and as such a message can only have a single thread created from it. +When called on a `GUILD_TEXT` channel, creates a `GUILD_PUBLIC_THREAD`. When called on a `GUILD_NEWS` channel, creates a `GUILD_NEWS_THREAD`. Does not work on a [`GUILD_FORUM`](#DOCS_RESOURCES_CHANNEL/start-thread-in-forum-channel) channel. The id of the created thread will be the same as the id of the source message, and as such a message can only have a single thread created from it. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -1130,7 +1140,7 @@ When called on a `GUILD_TEXT` channel, creates a `GUILD_PUBLIC_THREAD`. When cal ## Start Thread without Message % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/threads -Creates a new thread that is not connected to an existing message. The created thread defaults to a `GUILD_PRIVATE_THREAD`\*. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) on success, and a 400 BAD REQUEST on invalid parameters. Fires a [Thread Create](#DOCS_TOPICS_GATEWAY/thread-create) Gateway event. +Creates a new thread that is not connected to an existing message. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) on success, and a 400 BAD REQUEST on invalid parameters. Fires a [Thread Create](#DOCS_TOPICS_GATEWAY/thread-create) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -1150,7 +1160,53 @@ Creates a new thread that is not connected to an existing message. The created t \*\* The 3 day and 7 day archive durations require the server to be boosted. The [guild features](#DOCS_RESOURCES_GUILD/guild-object-guild-features) will indicate if that is possible for the guild. -\*\*\* In API v9, `type` defaults to `PRIVATE_THREAD` in order to match the behavior when thread documentation was first published. In API v10 this will be changed to be a required field, with no default. +\*\*\* In API v9, `type` defaults to `GUILD_PRIVATE_THREAD` in order to match the behavior when thread documentation was first published. In API v10 this will be changed to be a required field, with no default. + +## Start Thread in Forum Channel % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/threads + +Creates a new thread in a forum channel, and sends a message within the created thread. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) on success, and a 400 BAD REQUEST on invalid parameters. Fires a [Thread Create](#DOCS_TOPICS_GATEWAY/thread-create) and [Message Create](#DOCS_TOPICS_GATEWAY/message-create) Gateway event. + +- The type of the created thread is `GUILD_PUBLIC_THREAD`. +- See [message formatting](#DOCS_REFERENCE/message-formatting) for more information on how to properly format messages. +- The current user must have the `SEND_MESSAGES` permission (`CREATE_PUBLIC_THREADS` is ignored). +- The maximum request size when sending a message is **8MiB**. +- For the embed object, you can set every field except `type` (it will be `rich` regardless of if you try to set it), `provider`, `video`, and any `height`, `width`, or `proxy_url` values for images. +- Examples for file uploads are available in [Uploading Files](#DOCS_REFERENCE/uploading-files). +- Files must be attached using a `multipart/form-data` body as described in [Uploading Files](#DOCS_REFERENCE/uploading-files). +- Note that when sending a message, you must provide a value for at **least one of** `content`, `embeds`, or `files[n]`. + +> warn +> Discord may strip certain characters from message content, like invalid unicode characters or characters which cause unexpected message formatting. If you are passing user-generated strings into message content, consider sanitizing the data to prevent unexpected behavior and utilizing `allowed_mentions` to prevent unexpected mentions. + +> info +> This endpoint supports the `X-Audit-Log-Reason` header. + +###### JSON Params (For the Thread) + +| Field | Type | Description | +|----------------------------|----------|---------------------------------------------------------------------------------------------------------------------| +| name | string | 1-100 character channel name | +| auto_archive_duration?\* | integer | duration in minutes to automatically archive the thread after recent activity, can be set to: 60, 1440, 4320, 10080 | +| rate_limit_per_user? | ?integer | amount of seconds a user has to wait before sending another message (0-21600) | + +\* The 3 day and 7 day archive durations require the server to be boosted. The [guild features](#DOCS_RESOURCES_GUILD/guild-object-guild-features) will indicate if that is possible for the guild. + +###### JSON Params (For the Message) + +| Field | Type | Description | Required | +| -------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | +| content | string | the message contents (up to 2000 characters) | 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 | +| allowed_mentions | [allowed mention object](#DOCS_RESOURCES_CHANNEL/allowed-mentions-object) | allowed mentions for the message | 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 | +| files[n] \* | file contents | the contents of the file being sent | one of content, file, embed(s), sticker_ids | +| payload_json \* | string | JSON encoded body of non-file params | `multipart/form-data` only | +| attachments \* | array of partial [attachment](#DOCS_RESOURCES_CHANNEL/attachment-object) objects | attachment objects with filename and description | false | +| flags | integer | [message flags](#DOCS_RESOURCES_CHANNEL/message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS` can be set) | false | + +\* See [Uploading Files](#DOCS_REFERENCE/uploading-files) for details. ## Join Thread % PUT /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/thread-members/@me diff --git a/docs/topics/Gateway.md b/docs/topics/Gateway.md index 600ef52c23..20958e494b 100644 --- a/docs/topics/Gateway.md +++ b/docs/topics/Gateway.md @@ -827,7 +827,7 @@ Sent when a new guild channel is created, relevant to the current user. The inne #### Channel Update -Sent when a channel is updated. The inner payload is a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) object. This is not sent when the field `last_message_id` is altered. To keep track of the last_message_id changes, you must listen for [Message Create](#DOCS_TOPICS_GATEWAY/message-create) events. +Sent when a channel is updated. The inner payload is a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) object. This is not sent when the field `last_message_id` is altered. To keep track of the last_message_id changes, you must listen for [Message Create](#DOCS_TOPICS_GATEWAY/message-create) events (or [Thread Create](#DOCS_TOPICS_GATEWAY/thread-create) events for `GUILD_FORUM` channels). #### Channel Delete @@ -1184,7 +1184,7 @@ Sent when an invite is deleted. ### Messages > warn -> Unlike persistent messages, ephemeral messages are sent directly to the user and the bot who sent the message rather than through the guild channel. Because of this, ephemeral messages are tied to the [`DIRECT_MESSAGES` intent](#DOCS_TOPICS_GATEWAY/list-of-intents), and the message object won't include `guild_id` or `member`. +> Unlike persistent messages, ephemeral messages are sent directly to the user and the bot who sent the message rather than through the guild channel. Because of this, ephemeral messages are tied to the [`DIRECT_MESSAGES` intent](#DOCS_TOPICS_GATEWAY/list-of-intents), and the message object won't include `guild_id` or `member`. #### Message Create diff --git a/docs/topics/Opcodes_and_Status_Codes.md b/docs/topics/Opcodes_and_Status_Codes.md index b9e0efab04..a23c7eee09 100644 --- a/docs/topics/Opcodes_and_Status_Codes.md +++ b/docs/topics/Opcodes_and_Status_Codes.md @@ -150,6 +150,7 @@ Along with the HTTP error code, our API can also return more detailed error code | 10069 | Unknown Guild Welcome Screen | | 10070 | Unknown Guild Scheduled Event | | 10071 | Unknown Guild Scheduled Event User | +| 10087 | Unknown Tag | | 20001 | Bots cannot use this endpoint | | 20002 | Only bots can use this endpoint | | 20009 | Explicit content cannot be sent to the desired recipient(s) | @@ -184,6 +185,8 @@ Along with the HTTP error code, our API can also return more detailed error code | 30040 | Maximum number of prune requests has been reached. Try again later | | 30042 | Maximum number of guild widget settings updates has been reached. Try again later | | 30046 | Maximum number of edits to messages older than 1 hour reached. Try again later | +| 30047 | Maximum number of pinned threads in a forum channel has been reached | +| 30048 | Maximum number of tags in a forum channel has been reached | | 40001 | Unauthorized. Provide a valid token and try again | | 40002 | You need to verify your account in order to perform this action | | 40003 | You are opening direct messages too fast | @@ -195,6 +198,7 @@ Along with the HTTP error code, our API can also return more detailed error code | 40033 | This message has already been crossposted | | 40041 | An application command with that name already exists | | 40060 | Interaction has already been acknowledged | +| 40061 | Tag names must be unique | | 50001 | Missing access | | 50002 | Invalid account type | | 50003 | Cannot execute action on a DM channel | diff --git a/docs/topics/Permissions.md b/docs/topics/Permissions.md index abc0e07ce2..305b7b3f31 100644 --- a/docs/topics/Permissions.md +++ b/docs/topics/Permissions.md @@ -39,7 +39,7 @@ Below is a table of all current permissions, their integer values in hexadecimal | PRIORITY_SPEAKER | `0x0000000000000100` `(1 << 8)` | Allows for using priority speaker in a voice channel | V | | STREAM | `0x0000000000000200` `(1 << 9)` | Allows the user to go live | V | | VIEW_CHANNEL | `0x0000000000000400` `(1 << 10)` | Allows guild members to view a channel, which includes reading messages in text channels and joining voice channels | T, V, S | -| SEND_MESSAGES | `0x0000000000000800` `(1 << 11)` | Allows for sending messages in a channel (does not allow sending messages in threads) | T | +| SEND_MESSAGES | `0x0000000000000800` `(1 << 11)` | Allows for sending messages in a channel and creating threads in a forum (does not allow sending messages in threads) | T | | SEND_TTS_MESSAGES | `0x0000000000001000` `(1 << 12)` | Allows for sending of `/tts` messages | T | | MANAGE_MESSAGES \* | `0x0000000000002000` `(1 << 13)` | Allows for deletion of other users messages | T | | EMBED_LINKS | `0x0000000000004000` `(1 << 14)` | Links sent by users with this permission will be auto-embedded | T | diff --git a/docs/topics/Threads.md b/docs/topics/Threads.md index 4855671c9d..72482d2ba6 100644 --- a/docs/topics/Threads.md +++ b/docs/topics/Threads.md @@ -1,6 +1,6 @@ # Threads -[Threads](#DOCS_RESOURCES_CHANNEL/channel-object) are a new Discord feature. Threads can be thought of as temporary sub-channels inside an existing channel, to help better organize conversation in a busy channel. +[Threads](#DOCS_RESOURCES_CHANNEL/channel-object) can be thought of as temporary sub-channels inside an existing channel, to help better organize conversation in a busy channel. Threads have been designed to be very similar to [channel](#DOCS_RESOURCES_CHANNEL/channel-object) objects, and this topic aggregates all of the information about threads, which should all help to make migrating very straightforward. @@ -39,7 +39,7 @@ Additionally, there are a few new fields that are only available on threads: ## Public & Private Threads -Public threads are viewable by everyone who can view the parent channel of the thread. Public threads must be created from an existing message, but can be "orphaned" if that message is deleted. The created thread and the message it was started from will share the same id. The [type](#DOCS_RESOURCES_CHANNEL/channel-object-channel-types) of thread created matches the [type](#DOCS_RESOURCES_CHANNEL/channel-object-channel-types) of the parent channel. `GUILD_TEXT` channels [create](#DOCS_RESOURCES_CHANNEL/start-thread-with-message) `GUILD_PUBLIC_THREAD` and `GUILD_NEWS` channels [create](#DOCS_RESOURCES_CHANNEL/start-thread-with-message) `GUILD_NEWS_THREAD`. +Public threads are viewable by everyone who can view the parent channel of the thread. Public threads must be created from an existing message, but can be "orphaned" if that message is deleted. The created thread and the message it was started from will share the same id. The [type](#DOCS_RESOURCES_CHANNEL/channel-object-channel-types) of thread created matches the [type](#DOCS_RESOURCES_CHANNEL/channel-object-channel-types) of the parent channel. `GUILD_TEXT` channels [create](#DOCS_RESOURCES_CHANNEL/start-thread-from-message) `GUILD_PUBLIC_THREAD` and `GUILD_NEWS` channels [create](#DOCS_RESOURCES_CHANNEL/start-thread-from-message) `GUILD_NEWS_THREAD`. Private threads behave similar to Group DMs, but in a Guild. Private threads are always [created](#DOCS_RESOURCES_CHANNEL/start-thread-without-message) with the `GUILD_PRIVATE_THREAD` [type](#DOCS_RESOURCES_CHANNEL/channel-object-channel-types) and can only be created in `GUILD_TEXT` channels. @@ -161,3 +161,33 @@ Additionally, when a client loses access to a channel they are not removed from ### Unarchiving a thread Discord's clients only load active threads into memory on start. So when a thread is unarchived, there is no guarantee that the client has either the thread or whether they are a member, in memory. As such, the Gateway sends a [Thread Update](#DOCS_TOPICS_GATEWAY/thread-update) first, which contains the full channel object. And then sends a [Thread Member Update](#DOCS_TOPICS_GATEWAY/thread-member-update) to each member of the thread, so those clients know they are a member, and what their notification setting is. This event is not that valuable for bots right now, but is going to be received by bots, so is documented here none the less. + +# Forums + +A `GUILD_FORUM` channel is very similar (from an API perspective) to a `GUILD_TEXT` channel, except only threads can be created in that channel; messages cannot be sent directly in that channel. + +This feature is still in active development. Many aspects are in flux and subject to change, including (but not limited to): +- The name of the feature +- The permissions required to create threads in a forum (currently `SEND_MESSAGES` but may change) +- The shape of data exposed on the channel objects + +> warn +> Documentation for those features will be published in the future, once they have been finalized. We recommend developers avoid implementing features that are undocumented or are documented as still in flux. + +Listed below are some of the important details of forum channels and are safe to implement. Many bots can have reasonable support for the new channel simply by making it aware of the new channel type so it starts processing gateway events for that channel (and thus unlocking things like bots used for moderation): + +- Forums are a new channel type `15`. +- Forums do not allow messages to be sent in them. Endpoints like /channels/channel_id/messages will not work on a forum channel. +- Threads can be created in a forum channel. All threads in a forum are of type `GUILD_PUBLIC_THREAD`. These threads and messages within the thread have the same gateway events as threads in a normal text channel. +- The APIs for loading active & archived threads, joining & leaving a thread, and loading who is in a thread are unchanged and work the same for threads in a forum. +- The API to create a thread in a forum will create _both_ a thread and message in the same call, and as such requires passing in parameters for both the thread and message. The name and behavior of parameters is the same as they are for the existing create thread/message endpoints to simplify integrating with it. +- The message created by that API call will have the same id as the thread. +- The `last_message_id` field on the forum channel object tracks the id of the most recently created thread. It has the same behavior and requirements as it does for messages, namely that you will not receive a `CHANNEL_UPDATE` when it is changed. Instead clients should update the value when receiving [Thread Create](#DOCS_TOPICS_GATEWAY/thread-create). + +Listed below are things that are unlikely to change, but still might: + +- The `topic` field on a forum channel is what is shown in the "Guidelines" section visually +- The `rate_limit_per_user` field currently behaves the same as in a text channel, limiting how frequently threads can be created, _but its behavior may be changed before launching_. +- Threads in a forum have the same permissions behavior as threads in a text channel, inheriting all permissions from the parent channel, with just one exception: Creating a thread in a forum channel only requires the permission that is currently named `SEND_MESSAGES`. +- The first message in a forum thread can contain additional markdown for bulleted list and headings. +- A thread can be pinned within a forum. A thread that is pinned will have the `(1 << 1)` flag set. Archiving a pinned thread will unset the flag. A pinned thread will not auto archive.