Channels

A channel is a named place in a server where people talk. Every conversation lives in a channel or in a thread inside one. This page explains channel types, who sees which channels, and how clients learn about changes.

Channel types

Type	What it holds
`text`	Messages.
`voice`	Voice participants, plus a text chat.
`forum`	Threads. Messages go inside threads, not in the forum itself.
`separator`	Nothing. It’s a divider that groups channels in the list, with an optional `size` layout hint.

Text and voice channels are the only types that hold messages directly.

What a channel looks like

{
  "name": "general",
  "type": "text",
  "display_name": "General",
  "description": "Anything goes",
  "slow_mode_cooldown": 0,
  "last_message": 1760000000.123,
  "last_message_id": "5b1f7c2e-8d0a-4f5e-9a51-3c2d7e8f9a10",
  "last_message_by_user": 1759990000.5
}

Commands refer to a channel by its name. display_name is optional text to show instead. The server adds some fields when it sends a channel:

Text and voice channels get last_message, last_message_id, and last_message_by_user, which is when the caller last posted there. These help with unread dots and slow mode countdowns.
Voice channels get voice_state, the list of people in the call.
Forum channels get threads, a short list of recent threads. See threads and forums.

See the channel schema for every field.

Names

A channel name must:

Not be empty once surrounding spaces are trimmed.
Be at most 64 characters.
Not be . or .., and not contain a path separator such as /.
Be unique on the server.

Renaming a channel keeps its messages and threads.

Who sees which channels

channels_get returns the channels the caller can see, in server order. A channel is included when the caller passes its view rule. Separators are always included.

Each channel’s permissions object maps actions to roles. It decides who can send, edit, delete, react, pin, and create threads. See channel permissions.

Changing channels

Task	Command
Create a channel	`channel_create`
Change its name, settings, or permissions	`channel_update`
Change its position in the list	`channel_move`
Delete it	`channel_delete`

All four need manage_channels. Deleting a channel also deletes its messages and polls.

After a change, the server sends every connected client an up-to-date view:

If a channel’s settings changed but its name didn’t, clients that reported channel_get in their capabilities get a channel_get event with only that channel.
In every other case, clients get a full channels_get list filtered for them.

The server also sends a user a new channels_get when their roles change which channels they can view.