Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
14.4 KB
Raw Blame
---
# 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 &lt;&lt; 1 | PINNED | The post is the pinned post of its channel |
| 1 &lt;&lt; 4 | REQUIRE_TAG | A new post, or a change to the tags of a post, needs at least one tag |
| 1 &lt;&lt; 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 &lt;&lt; 13 | NEW_FORUM_THREADS_OFF | No push notification for a new post in the channel |
| 1 &lt;&lt; 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`.