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

Initial forums documentation #4761

Merged
merged 4 commits into from
Apr 8, 2022
Merged

Initial forums documentation #4761

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4ce68db
Initial forums documentation
ajpalkovic Apr 6, 2022
3c5697a
channel -> thread
ajpalkovic Apr 7, 2022
3e41bdc
document last_message_id changes for forums too
ajpalkovic Apr 7, 2022
2322d9f
typo
ajpalkovic Apr 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/Change_Log.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
66 changes: 61 additions & 5 deletions docs/resources/Channel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This phrasing makes it seem like you don't need to specify type 11 when using this endpoint or that you can't have private threads in a forum. Unfortunately not passing type leads to a 50024 error. I'm unsure if that's a bug.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pretty sure this endpoint is broken atm, if you do include the type field, it will ignore the message data, and if you don't it'll give you an error.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is one of those fun, but rare, times where the docs are ahead of the code lol.
Route isn't live yet, and I'll need to migrate our callers over to it gracefully, so for at least a month, our clients will have to opt-in to the new behavior, and then once updates are fully available everywhere I'll switch the new behavior to be the default for forums and remove the old one.

- 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 |
ajpalkovic marked this conversation as resolved.
Show resolved Hide resolved
| 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

Expand Down
4 changes: 4 additions & 0 deletions docs/topics/Opcodes_and_Status_Codes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand Down Expand Up @@ -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 |
Expand All @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/topics/Permissions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
Loading