Forums
A forum channel has posts, and every post is a public thread with its own first message. A media channel is a forum channel that can hide media download options.
Neither channel type has messages of its own. Creating a message, adding a reaction or pinning a message in the channel itself returns 400 CANNOT_SEND_MESSAGES_IN_NON_TEXT_CHANNEL. Listing messages or pins and the typing indicator return 400 INVALID_CHANNEL_TYPE.
A user request to a route below without the channel_threads client capability gets 404 NOT_FOUND. A channel_id that does not exist or is outside a guild gets the same 404.
Forum channel fields
Section titled “Forum channel fields”A forum or media channel is a channel object of type 15 or 16 with these fields.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| topic | ?string | The guidelines of the channel (1-4,096 characters) |
| last_message_id1 | ?snowflake | The ID of the newest post |
| flags | integer | The channel flags of the channel |
| available_tags | array[forum tag object] | The tags a post can apply (max 20) |
| default_reaction_emoji | ?default reaction object | The reaction clients show on each post |
| default_sort_order | ?integer | The default sort order of posts |
| default_forum_layout?2 | integer | The default layout of posts |
| default_tag_setting3 | string | The default tag matching of a post search |
| default_auto_archive_duration4 | ?integer | The default auto archive duration, which new posts don't use |
| default_thread_rate_limit_per_user5 | integer | The slowmode interval in seconds new threads inherit |
1 Creating a post updates it without sending a Channel Update event
2 Only on a forum channel, and 0 when none is stored
3 match_some when none is stored
4 A post created with no auto_archive_duration archives after 4320 minutes
5 A new post gets it when Start thread sets no rate_limit_per_user, and it is 0 when none is set
In a forum, rate_limit_per_user limits how often one member creates a post. Bots and members with BYPASS_SLOWMODE are exempt.
Example
Section titled “Example”{ "id": "1501314428688998300", "type": 15, "guild_id": "1501314428688990000", "name": "help", "position": 4, "permission_overwrites": [], "parent_id": null, "last_message_id": "1501320250000000000", "last_pin_timestamp": null, "topic": "One question per post", "nsfw": false, "nsfw_override": null, "content_warning_level": 0, "content_warning_text": null, "rate_limit_per_user": 0, "flags": 16, "default_auto_archive_duration": null, "default_thread_rate_limit_per_user": 0, "available_tags": [ {"id": "1501314428688998301", "name": "Solved", "moderated": false, "emoji_id": null, "emoji_name": null} ], "default_reaction_emoji": null, "default_sort_order": null, "default_tag_setting": "match_some", "default_forum_layout": 0}Forum post object
Section titled “Forum post object”Start thread returns a forum post, which is a thread object with its first message.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| message | message object | The first message of the post, with the same ID as the post |
Channel types
Section titled “Channel types”| Value | Name | Description |
|---|---|---|
| 15 | GUILD_FORUM | Guild channel that has posts |
| 16 | GUILD_MEDIA | Forum channel that can hide media download options |
Channel flags
Section titled “Channel flags”| Value | Name | Description |
|---|---|---|
| 1 << 1 | PINNED | The post is the pinned post of its channel |
| 1 << 4 | REQUIRE_TAG | A new post, or a change to the tags of a post, needs at least one tag |
| 1 << 15 | HIDE_MEDIA_DOWNLOAD_OPTIONS | Clients hide the media download options of the channel |
Pinning a second post in a channel returns 400 MAX_PINNED_THREADS_IN_FORUM, and archiving a post unpins it. A post with no tag in a REQUIRE_TAG channel returns 400 FORUM_TAG_REQUIRED. Setting HIDE_MEDIA_DOWNLOAD_OPTIONS on a forum channel returns 400 HIDE_MEDIA_DOWNLOAD_OPTION_MEDIA_ONLY, and setting any other bit outside this table on a channel or post returns 400 INVALID_FORM_BODY.
Forum tag object
Section titled “Forum tag object”A post lists the IDs of its tags in applied_tags.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the tag |
| name | string | The name of the tag (1-50 characters) |
| moderated | boolean | Whether only thread moderators can apply or remove the tag |
| emoji_id | ?snowflake | The ID of a custom emoji of this guild |
| emoji_name | ?string | A single Unicode emoji |
At most one of emoji_id and emoji_name is set. Tag names are unique within a channel, and the check is case-sensitive. Only a thread moderator can apply or remove a moderated tag.
Default reaction object
Section titled “Default reaction object”The reaction clients show on each post.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| emoji_id | ?snowflake | The ID of a custom emoji of this guild, or null for a Unicode emoji |
| emoji_name | ?string | A single Unicode emoji, or null for a custom emoji |
Forum sort orders
Section titled “Forum sort orders”| Value | Name | Description |
|---|---|---|
| 0 | LATEST_ACTIVITY | Sort posts by latest activity |
| 1 | CREATION_TIME | Sort posts by creation time |
Forum layouts
Section titled “Forum layouts”| Value | Name | Description |
|---|---|---|
| 0 | DEFAULT | No layout is set |
| 1 | LIST | Show posts as a list |
| 2 | GRID | Show posts as a grid of tiles |
Forum tag settings
Section titled “Forum tag settings”| Value | Description |
|---|---|
| match_some | A post matches when it applies any of the searched tags |
| match_all | A post matches when it applies every searched tag |
Creating and modifying a forum
Section titled “Creating and modifying a forum”Create guild channel with type 15 or 16 and Modify channel on a forum or media channel accept these fields in addition to the common guild channel fields.
| Field | Type | Description |
|---|---|---|
| topic? | ?string | The guidelines of the channel (1-4,096 characters) |
| available_tags?1 | array[forum tag object] | The complete tag set (max 20) |
| default_reaction_emoji? | ?default reaction object | The default reaction |
| default_sort_order? | ?integer | The sort order |
| default_forum_layout?2 | ?integer | The layout, where null resets it to 0 |
| default_tag_setting? | ?string | The tag matching default, where null resets it to match_some |
| default_auto_archive_duration? | ?integer | The default auto archive duration, which new posts don't use |
| default_thread_rate_limit_per_user? | ?integer | The slowmode interval in seconds new threads inherit (0-21,600) |
| flags? | integer | The channel flags of the channel |
1 An entry with id keeps that tag, an entry without one creates a tag, and a stored tag missing from the array is deleted
2 A media channel ignores it
Null clears a field unless its description says otherwise. A request that sets these fields can fail with these errors.
| Status | Code | Condition |
|---|---|---|
| 400 | MAX_FORUM_TAGS | available_tags has more than 20 tags |
| 400 | FORUM_TAG_NAMES_MUST_BE_UNIQUE | Two tags have the same name |
| 400 | INVALID_FORM_BODY | A tag or the default reaction sets both emoji fields, or an emoji_name that isn't one Unicode emoji |
| 400 | NO_TAGS_AVAILABLE_TO_NON_MODERATORS | REQUIRE_TAG is set and no unmoderated tag is left |
| 404 | UNKNOWN_FORUM_TAG | A tag has an id the channel doesn't have |
| 404 | UNKNOWN_EMOJI | An emoji_id is not an emoji of this guild |
| 429 | RESOURCE_LOCKED | Another tag change is running |
Create forum tag
Section titled “Create forum tag”POST/v1/channels/{channel_id}/tagsAdds a tag to a forum or media channel and sends a Channel Update event. You need MANAGE_CHANNELS.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| name | string | The name of the tag (1-50 characters) |
| moderated? | boolean | Whether only thread moderators can apply or remove the tag (default false) |
| emoji_id? | ?snowflake | The ID of a custom emoji of this guild, or null for none |
| emoji_name? | ?string | A single Unicode emoji (max 64 characters), or null for none |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | channel object | The tag was added |
| 400 | error response | The channel has 20 tags, with MAX_FORUM_TAGS |
| 400 | error response | The name is taken, with FORUM_TAG_NAMES_MUST_BE_UNIQUE |
| 400 | error response | No unmoderated tag would be left, with NO_TAGS_AVAILABLE_TO_NON_MODERATORS |
| 404 | error response | The emoji is not an emoji of this guild, with UNKNOWN_EMOJI |
| 429 | error response | Another tag change is running, with RESOURCE_LOCKED |
The rate limit is 10 requests per 10 seconds, on the channel:forum_tags::channel_id bucket.
Modify forum tag
Section titled “Modify forum tag”PUT/v1/channels/{channel_id}/tags/{tag_id}Replaces a tag and sends a Channel Update event, and any field you omit resets to its default. You need MANAGE_CHANNELS.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| name | string | The name of the tag (1-50 characters) |
| moderated? | boolean | Whether only thread moderators can apply or remove the tag (default false) |
| emoji_id? | ?snowflake | The ID of a custom emoji of this guild, or null for none |
| emoji_name? | ?string | A single Unicode emoji (max 64 characters), or null for none |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | channel object | The tag was replaced |
| 400 | error response | The name is taken, with FORUM_TAG_NAMES_MUST_BE_UNIQUE |
| 400 | error response | No unmoderated tag would be left, with NO_TAGS_AVAILABLE_TO_NON_MODERATORS |
| 404 | error response | The tag or emoji is unknown, with UNKNOWN_FORUM_TAG or UNKNOWN_EMOJI |
| 429 | error response | Another tag change is running, with RESOURCE_LOCKED |
The rate limit is 10 requests per 10 seconds, on the channel:forum_tags::channel_id bucket.
Delete forum tag
Section titled “Delete forum tag”DELETE/v1/channels/{channel_id}/tags/{tag_id}Removes a tag and sends a Channel Update event, and HTTP responses leave it out of each post's applied_tags. You need MANAGE_CHANNELS.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | channel object | The tag was removed |
| 400 | error response | The removal leaves REQUIRE_TAG with no unmoderated tag, with NO_TAGS_AVAILABLE_TO_NON_MODERATORS |
| 404 | error response | The channel has no such tag, with UNKNOWN_FORUM_TAG |
| 429 | error response | Another tag change is running, with RESOURCE_LOCKED |
The rate limit is 10 requests per 10 seconds, on the channel:forum_tags::channel_id bucket.
Get forum post data
Section titled “Get forum post data”POST/v1/channels/{channel_id}/post-dataReturns the owner and first message of each requested post. You need READ_MESSAGE_HISTORY.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| thread_ids | array[snowflake] | The IDs of the posts (1-100) |
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| threads1 | map[snowflake, post data object] | The post data keyed by post ID |
1 An ID that isn't a post in this channel maps to an object with null owner and first_message
Post data object
Section titled “Post data object”| Field | Type | Description |
|---|---|---|
| owner2 | ?guild member object | The guild member who created the post |
| first_message3 | ?message object | The first message of the post |
2 Null for a post a webhook created, or when the creator left the guild
3 Null when the first message was deleted
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | post data map | Post data was returned |
| 403 | error response | The age check fails, with NSFW_CONTENT_AGE_RESTRICTED |
The rate limit is 20 requests per 10 seconds, on the channel:post_data::channel_id bucket.
Webhooks in forums
Section titled “Webhooks in forums”A webhook in a forum or media channel creates a post with thread_name and applied_tags, or posts in an existing one with thread_id, through Execute webhook. Posting in an archived post that isn't locked unarchives it and sends a Thread Update event.
New post notifications
Section titled “New post notifications”A channel notification override stores these two flags bits.
| Value | Name | Description |
|---|---|---|
| 1 << 13 | NEW_FORUM_THREADS_OFF | No push notification for a new post in the channel |
| 1 << 14 | NEW_FORUM_THREADS_ON | Fluxer stores it but doesn't use it |
A new post sends a push notification when the channel's notification level is all messages. A mute on the guild, category or channel stops it, and so does NEW_FORUM_THREADS_OFF.