A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Forums
description: Forum and media channels, forum tags, post data, and webhooks that post into a forum.
---
import RouteHeader from '@/components/RouteHeader.astro';
A forum channel has posts, and every post is a public [thread](/http-api/threads/) 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](/http-api/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
A forum or media channel is a [channel object](/http-api/channels/#channel-object) of type `15` or `16` with these fields.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| topic | ?string | The guidelines of the channel (1-4,096 characters) |
| last_message_id<sup>1</sup> | ?snowflake | The ID of the newest post |
| flags | integer | The [channel flags](#channel-flags) of the channel |
| available_tags | array[[forum tag](#forum-tag-object) object] | The tags a post can apply (max 20) |
| default_reaction_emoji | ?[default reaction](#default-reaction-object) object | The reaction clients show on each post |
| default_sort_order | ?integer | The default [sort order](#forum-sort-orders) of posts |
| default_forum_layout?<sup>2</sup> | integer | The default [layout](#forum-layouts) of posts |
| default_tag_setting<sup>3</sup> | string | The default [tag matching](#forum-tag-settings) of a post search |
| default_auto_archive_duration<sup>4</sup> | ?integer | The default [auto archive duration](/http-api/threads/#auto-archive-durations), which new posts don't use |
| default_thread_rate_limit_per_user<sup>5</sup> | integer | The slowmode interval in seconds new threads inherit |
<sup>1</sup> Creating a post updates it without sending a [Channel Update](/gateway/events/#channel-update) event
<sup>2</sup> Only on a forum channel, and `0` when none is stored
<sup>3</sup> `match_some` when none is stored
<sup>4</sup> A post created with no `auto_archive_duration` archives after 4320 minutes
<sup>5</sup> A new post gets it when [Start thread](/http-api/threads/#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
```json
{
"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
[Start thread](/http-api/threads/#start-thread) returns a forum post, which is a [thread object](/http-api/threads/#thread-object) with its first message.
### Structure
| Field | Type | Description |
| --- | --- | --- |
| message | [message](/http-api/messages/#message-object) object | The first message of the post, with the same ID as the post |
## 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) |
## 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
A post lists the IDs of its tags in `applied_tags`.
### 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](/http-api/threads/#thread-moderators) can apply or remove a moderated tag.
## Default reaction object
The reaction clients show on each post.
### 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
| Value | Name | Description |
| --- | --- | --- |
| 0 | LATEST_ACTIVITY | Sort posts by latest activity |
| 1 | CREATION_TIME | Sort posts by creation time |
## 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
| 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
[Create guild channel](/http-api/guild-channels/#create-guild-channel) with `type` `15` or `16` and [Modify channel](/http-api/channels/#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?<sup>1</sup> | array[[forum tag](#forum-tag-object) object] | The complete tag set (max 20) |
| default_reaction_emoji? | ?[default reaction](#default-reaction-object) object | The default reaction |
| default_sort_order? | ?integer | The [sort order](#forum-sort-orders) |
| default_forum_layout?<sup>2</sup> | ?integer | The [layout](#forum-layouts), where null resets it to `0` |
| default_tag_setting? | ?string | The [tag matching](#forum-tag-settings) default, where null resets it to `match_some` |
| default_auto_archive_duration? | ?integer | The default [auto archive duration](/http-api/threads/#auto-archive-durations), 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](#channel-flags) of the channel |
<sup>1</sup> An entry with `id` keeps that tag, an entry without one creates a tag, and a stored tag missing from the array is deleted
<sup>2</sup> 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
<RouteHeader method="POST" path="/v1/channels/{channel_id}/tags" bot auditReason />
Adds a tag to a forum or media channel and sends a [Channel Update](/gateway/events/#channel-update) event. You need `MANAGE_CHANNELS`.
### 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
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [channel](/http-api/channels/#channel-object) object | The tag was added |
| 400 | [error response](/http-api/#error-response) | The channel has 20 tags, with `MAX_FORUM_TAGS` |
| 400 | [error response](/http-api/#error-response) | The name is taken, with `FORUM_TAG_NAMES_MUST_BE_UNIQUE` |
| 400 | [error response](/http-api/#error-response) | No unmoderated tag would be left, with `NO_TAGS_AVAILABLE_TO_NON_MODERATORS` |
| 404 | [error response](/http-api/#error-response) | The emoji is not an emoji of this guild, with `UNKNOWN_EMOJI` |
| 429 | [error response](/http-api/#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
<RouteHeader method="PUT" path="/v1/channels/{channel_id}/tags/{tag_id}" bot auditReason />
Replaces a tag and sends a [Channel Update](/gateway/events/#channel-update) event, and any field you omit resets to its default. You need `MANAGE_CHANNELS`.
### 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
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [channel](/http-api/channels/#channel-object) object | The tag was replaced |
| 400 | [error response](/http-api/#error-response) | The name is taken, with `FORUM_TAG_NAMES_MUST_BE_UNIQUE` |
| 400 | [error response](/http-api/#error-response) | No unmoderated tag would be left, with `NO_TAGS_AVAILABLE_TO_NON_MODERATORS` |
| 404 | [error response](/http-api/#error-response) | The tag or emoji is unknown, with `UNKNOWN_FORUM_TAG` or `UNKNOWN_EMOJI` |
| 429 | [error response](/http-api/#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
<RouteHeader method="DELETE" path="/v1/channels/{channel_id}/tags/{tag_id}" bot auditReason />
Removes a tag and sends a [Channel Update](/gateway/events/#channel-update) event, and HTTP responses leave it out of each post's `applied_tags`. You need `MANAGE_CHANNELS`.
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [channel](/http-api/channels/#channel-object) object | The tag was removed |
| 400 | [error response](/http-api/#error-response) | The removal leaves `REQUIRE_TAG` with no unmoderated tag, with `NO_TAGS_AVAILABLE_TO_NON_MODERATORS` |
| 404 | [error response](/http-api/#error-response) | The channel has no such tag, with `UNKNOWN_FORUM_TAG` |
| 429 | [error response](/http-api/#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
<RouteHeader method="POST" path="/v1/channels/{channel_id}/post-data" bot />
Returns the owner and first message of each requested post. You need `READ_MESSAGE_HISTORY`.
### JSON body
| Field | Type | Description |
| --- | --- | --- |
| thread_ids | array[snowflake] | The IDs of the posts (1-100) |
### Response body
| Field | Type | Description |
| --- | --- | --- |
| threads<sup>1</sup> | map[snowflake, [post data](#post-data-object) object] | The post data keyed by post ID |
<sup>1</sup> An ID that isn't a post in this channel maps to an object with null `owner` and `first_message`
#### Post data object
| Field | Type | Description |
| --- | --- | --- |
| owner<sup>2</sup> | ?[guild member](/http-api/guild-members/#guild-member-object) object | The guild member who created the post |
| first_message<sup>3</sup> | ?[message](/http-api/messages/#message-object) object | The first message of the post |
<sup>2</sup> Null for a post a webhook created, or when the creator left the guild
<sup>3</sup> Null when the first message was deleted
### Response
| Status | Body | Condition |
| --- | --- | --- |
| 200 | [post data](#response-body) map | Post data was returned |
| 403 | [error response](/http-api/#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
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](/http-api/webhooks/#execute-webhook). Posting in an archived post that isn't locked unarchives it and sends a [Thread Update](/gateway/threads/#thread-update) event.
## New post notifications
A [channel notification override](/http-api/users/settings/#channel-notification-override-object) 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`.