channel_update

channel_update changes one or more settings of an existing channel. Fields you leave out of updates stay as they are.

Request

{
  "cmd": "channel_update",
  "current_name": "general",
  "updates": {
    "display_name": "General chat",
    "slow_mode_cooldown": 0
  }
}

Field	Type	Required	Description
current_name	string	Yes	The channel’s name now. Case-sensitive.
updates	object	Yes	The settings to change. Must contain at least one of the fields below.
updates.name	string	No	New name. Trimmed, then 1 to 64 characters, not . or .., and no /. Must not belong to another channel.
updates.type	string	No	text, voice, forum, or separator.
updates.display_name	string or null	No	Name to show in the UI. null clears it.
updates.description	string or null	No	Channel topic. null clears it.
updates.icon	string or null	No	Absolute http or https icon URL with no whitespace. null clears it.
updates.permissions	object	No	New channel permission map. It replaces the whole stored map; keys you leave out go back to the server defaults.
updates.size	number or null	No	Separator size. null clears it.
updates.max_message_age	number	No	Message retention in seconds, rounded down. 0 clears it. The server does not delete old messages itself.
updates.slow_mode_cooldown	number	No	Seconds between messages per user, rounded down. 0 turns slow mode off.

The server ignores unknown keys in updates.

Renaming a channel keeps its messages, threads, and mentions. Clients should update any stored references from the old name to the new one.

Caution

updates.permissions is not merged with the current permissions. To change one permission, send the full map with that one key changed.

Response

{ "cmd": "channel_update", "val": true }

Before this reply, every logged-in connection, including yours, receives the updated channel:

• If the name did not change, clients that reported the channel_get capability get a channel_get frame for the channel. Other clients get a full channels_get list.
• If the name changed, every client gets a full channels_get list.

The change is also recorded in the audit log.

Permissions

Requires the manage_channels server permission. Without it the server returns Access denied: 'manage_channels' permission required. A user in a timeout gets a rate_limit frame instead.

Errors

val	When
Channel not found	No channel is named current_name.
updates object has no supported fields	updates has none of the fields in the table.
Channel icon must be an absolute HTTP or HTTPS URL	updates.icon is not a valid web URL.
Channel name must be at most 64 characters	updates.name is too long after trimming.
Channel name cannot contain path separators	updates.name is ., .., or contains /.
Channel with new name already exists	Another channel already uses updates.name.
Failed to update channel '<name>'	The server could not save the change.

A validation message is returned when current_name or updates is missing, updates is empty, or a field has the wrong type or a negative duration.

See also

• channel_create
• Channel schema
• Roles and permissions