Threads & forums

A forum is a channel of type forum that holds threads instead of messages. A thread is a named conversation inside a forum, with its own message history. Use forums for topics that people come back to, such as support questions or feature ideas.

What a thread looks like

{
  "id": "9d2b6f4a-3c1e-4a7b-8f5d-2e6c1b0a9f83",
  "name": "Login fails on mobile",
  "parent_channel": "support",
  "created_by": "mist",
  "created_at": 1760000000.123,
  "locked": false,
  "archived": false,
  "participants": ["mist"],
  "message_count": 12
}

parent_channel is the forum the thread belongs to. See the thread schema for every field.

Permissions come from the forum

A thread has no permission rules of its own. It uses the rules of its parent forum:

Anyone who can view the forum can view and read its threads.
Posting in a thread needs the forum’s send rule, and the thread must not be locked.
Creating a thread needs the forum’s create_thread rule.

Participants

A thread keeps a list of participants. The creator is the first one. Others join with thread_join and leave with thread_leave.

Participation doesn’t control access. Leaving a thread doesn’t stop you reading it, and joining doesn’t let you post if the forum’s rules don’t allow it. It decides which threads appear in your forum’s summary list, described next.

Listing threads

There are two ways to get a forum’s threads:

The threads field in channels_get is a short, personal list. It includes a thread only if you’re a participant (or it has no participants) and its last message is less than seven days old. Pinned threads come first.
threads_get lists every thread in a forum, a page at a time, without those filters.

Use the channels_get list for a sidebar and threads_get for a full forum view.

Thread states

State	Effect	Set with
Archived	Still readable. Posting a message reopens it. History is kept.	`archived` in `thread_update`
Locked	Nobody can post in it or join it.	`locked` in `thread_update`
Pinned	Listed first in the forum.	`thread_pin`, `thread_unpin`

Who can manage a thread

Action	Thread creator	Thread manager
Rename or archive	Yes	Yes
Delete	Yes	Yes
Lock or unlock	No	Yes
Pin or unpin	No	Yes

A thread manager is someone with manage_threads, the admin role, or administrator. If a creator sends locked, the server ignores it.

Messages in threads

Message commands take a thread_id. If you also send channel, it must be the thread’s parent forum. Events about a thread include both thread_id and the parent channel, so a client can file them under the right forum.

Thread events

Creating, updating, deleting, joining, leaving, pinning, and unpinning a thread are broadcast to everyone who can view the forum.