Skip to content

Commit

Permalink
Initial forums documentation
Browse files Browse the repository at this point in the history 
Note: We are documenting forums in two phases. Today is phase 1 contianing the things that are least likely to change, and are easy to implement, and will provide the most value if implemented early. We'll followup in the future with full documentation at a future time.
  • Loading branch information
@ajpalkovic
ajpalkovic committed Apr 7, 2022
1 parent 9bcff53 commit 4ce68db
Show file tree
Hide file tree
Showing 5 changed files with 103 additions and 8 deletions.
6 changes: 6 additions & 0 deletions docs/Change_Log.md
View file
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
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`.
- 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

Expand Down
4 changes: 4 additions & 0 deletions docs/topics/Opcodes_and_Status_Codes.md
View file
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
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

0 comments on commit 4ce68db

Please sign in to comment.