Guild channels

A guild channel is one of the rooms a guild is divided into, including the categories that group them. The operations here list, create, and reorder a guild’s channels, and the Channels resource defines the channel object and every per-channel operation.

Access rules

Every operation here returns 404 UNKNOWN_GUILD for a guild that does not exist. A caller who is not a member of an existing guild receives 403 MISSING_PERMISSIONS.

A request whose path names a guild that has UNAVAILABLE_FOR_EVERYONE is refused with 403 MISSING_ACCESS before the operation runs.

Guild channel types

These are the channel types that can exist inside a guild, and exactly the values Create guild channel accepts in type.

Value	Name	Description
0	GUILD_TEXT	Text channel that has messages and slowmode
2	GUILD_VOICE	Voice channel that has messages, voice sessions, and Go Live streams
4	GUILD_CATEGORY	Category that groups other guild channels and supplies inherited permission overwrites
998	GUILD_LINK	Channel whose only content is an external destination URL

Create permission overwrite object

The initial overwrite collection supplied when a channel is created. The stored form returned afterwards is the permission overwrite object.

Structure

Field	Type	Description
id	snowflake	The ID of the role or member the overwrite targets
type1	integer	Permission overwrite type
allow?2	decimal string	The permission bits the overwrite grants (default 0)
deny?2	decimal string	The permission bits the overwrite removes (default 0)

¹ Required. 0 names a role and 1 names a member, and no other value is accepted

² A decimal string of at most 9223372036854775807, or a JSON integer of at most 9007199254740991. Null is rejected

A larger decimal string returns 400 INVALID_FORM_BODY with the code INTEGER_OUT_OF_INT64_RANGE. A JSON number outside the safe integer range returns INVALID_INTEGER_FORMAT, and so does a string that is not all digits.

A bit that names no defined permission never fails the authority comparison described by Create guild channel. It is stored as supplied and echoed back by every later read of the channel.

A bit set in both masks resolves to an allow during permission computation.

Example

{
  "id": "1501314428688998182",
  "type": 0,
  "allow": "1024",
  "deny": "2048"
}

Channel position object

One entry of the bulk hierarchy update. Entries are applied in array order, each against the result of the previous one.

Structure

Field	Type	Description
id	snowflake	The ID of the channel to move
position?1	integer	Index among the destination siblings (minimum 0)
parent_id?2	?snowflake	New parent category, or null to move the channel to the guild root
preceding_sibling_id?3	?snowflake	Sibling that sits directly before this channel, or null to place it first
lock_permissions?4	boolean	Whether to copy the destination category’s overwrites onto the moved channel (default false)

¹ Read only when preceding_sibling_id is omitted. When preceding_sibling_id is sent, including as null, FiveCord ignores position

² An omitted field keeps the channel’s current parent. A category given any parent is refused with CATEGORIES_CANNOT_HAVE_PARENTS

³ A preceding sibling must share the destination parent, so a category is valid here only when the moved channel’s destination is the guild root

⁴ The copy runs only when the same entry also moves the channel into a category, and it replaces the moved channel’s overwrites

A position beyond the destination’s last sibling places the channel last. Omitting both position and preceding_sibling_id places a voice channel last and any other channel directly before the first voice sibling.

Naming a category as the preceding sibling places the moved channel after that category and after every channel already inside it.

Example

{
  "id": "1501314428688998182",
  "parent_id": "1501314428688998100",
  "preceding_sibling_id": null,
  "lock_permissions": true
}

List guild channels

GET/v1/guilds/{guild_id}/channelsBot

Returns every channel object in the guild that the authenticated member can see. Membership is the only requirement.

FiveCord evaluates channel visibility per channel. A channel is included when the member holds VIEW_CHANNEL in it, or when the member holds temporary access to it through a voice transition. A category is included when at least one child grants the member VIEW_CHANNEL. A member with no visible channel receives an empty array.

Every visible channel arrives in one body

The route accepts no limit and no cursor. Each entry is a complete channel object whose permission_overwrites array is always present and always complete.

A guild holds at most the instance-configured max_guild_channels limit, which defaults to 500.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response

Status	Body	Condition
200	array[channel object]	Visible channels were returned
403	error response	Caller is not a member of the guild, returning MISSING_PERMISSIONS
404	error response	Guild does not exist, returning UNKNOWN_GUILD

Rate limit

60 requests per 10 seconds for each authenticated user and guild ID, on the guild:channels:list::guild_id bucket.

Create guild channel

POST/v1/guilds/{guild_id}/channelsBotAudit reasonMFA

Creates a guild channel and returns its channel object with status 200. Requires MANAGE_CHANNELS at guild level. Emits a Channel Create Gateway event.

Limitations

• Supplying permission_overwrites also requires MANAGE_ROLES at guild level.

MANAGE_CHANNELS is an elevated permission, so it also requires an enrolled multi-factor authenticator when the guild MFA level is elevated and the caller is not the guild owner.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

JSON body

type is required and decides which kind of channel is created. Every type accepts the same field set, so a field that has no meaning for the selected type is accepted and then ignored.

Field	Type	Description
type	integer	Guild channel type
name12	string	Channel name (1-100 characters after normalisation)
topic?	?string	Channel topic (1-1024 characters)
url?3	?string	Destination URL for a link channel
parent_id?4	?snowflake	Parent category
bitrate?511	?integer	Voice channel bitrate in bits per second (8000-384000, default 64000)
user_limit?56	?integer	Voice channel occupancy limit (0-99, default 0)
voice_connection_limit?5	?integer	Simultaneous voice connections permitted for one user in a voice channel (1-100, default 5)
rate_limit_per_user?	?integer	Slowmode interval in seconds (0-21600, default 0)
permission_overwrites?7	array[create permission overwrite object]	Complete initial overwrite collection
nsfw?8	boolean	Legacy age restriction for this channel (default false)
nsfw_override?8	?boolean	Explicit age restriction, or null to inherit from the parent category and then the guild
content_warning_level?9	integer	Content warning level (default 0)
content_warning_text?10	?string	Content warning text (max 200 characters), or null to inherit

¹ Normalisation strips control, join, bidirectional, and tag code points, collapses whitespace runs to one space, and trims. An empty result is rejected with NAME_EMPTY_AFTER_NORMALIZATION

² A text channel name is also lowercased, its whitespace replaced with hyphens, and ASCII punctuation other than -, ., and _ removed, unless the guild has TEXT_CHANNEL_FLEXIBLE_NAMES. That pass rewrites the stored name and never fails the request

³ An http or https URL of at most 2048 characters with a host and no embedded credentials. It is stored for every channel type

⁴ Names a category in the same guild. A category cannot be given a parent

⁵ Stored only for the voice variant, where the stated default applies when the field is omitted or null, and discarded for every other type

⁶ The value 0 means no occupancy limit

⁷ When omitted, a new channel with a parent category copies that category’s current overwrites. A present field replaces that inheritance completely, including with an empty array. Null is rejected

⁸ nsfw_override takes precedence, and nsfw supplies the value only when nsfw_override is absent. Omitting both stores an explicit false, and only a null nsfw_override inherits

⁹ The value 1 enables the warning on this channel. Every other accepted value stores 0 and inherits from the parent category and then the guild

¹⁰ The value is trimmed, and an empty result is stored as null

¹¹ The stored value is capped at 96000 unless the guild holds an audio bitrate feature. A higher value is stored at the cap rather than rejected

A value longer than 10000 characters is rejected with STRING_LENGTH_INVALID before normalisation runs. A parent that does not exist in this guild returns INVALID_PARENT_CHANNEL, and one that is not a category returns PARENT_MUST_BE_CATEGORY.

The guild holds at most the instance-configured max_guild_channels limit, defaulting to 500, and a parent category holds at most max_channels_per_category, defaulting to 50. Reaching the guild limit returns 400 MAX_GUILD_CHANNELS and reaching the category limit returns 400 MAX_CATEGORY_CHANNELS. Each error message states the resolved limit. The new channel is created with no RTC region.

The new channel takes a position derived from its siblings. A category, and a channel created with no parent, is placed after the highest position in the guild. A voice channel created inside a category is placed after the last voice sibling, or after the last text or link sibling when the category holds no voice channel. A text or link channel is placed after the last text or link sibling, and a channel with no such sibling is placed directly after the category itself. The rest of the guild is not renumbered, so two channels can hold the same stored position until the next hierarchy update renumbers them.

Overwrites are checked against the parent category

FiveCord compares the allowed bits of every supplied overwrite against the caller’s effective permissions in the parent category, or in the guild when no parent is supplied. A bit the caller does not hold there fails the entire request with 403 MISSING_PERMISSIONS.

Only the allowed mask is compared, so a supplied deny is stored without any authority check. A caller holding ADMINISTRATOR in that context holds every bit, and every requested bit passes.

Response

Status	Body	Condition
200	channel object	Channel was created
40012	error response	Body, type, name, parent, URL, voice setting, or content warning text is invalid, a channel limit is reached, or the caller has no enrolled authenticator in an elevated-MFA guild
403	error response	Caller lacks MANAGE_CHANNELS, is not a member of the guild, supplied overwrites without MANAGE_ROLES, or allowed a permission they do not hold in the parent context, each returning MISSING_PERMISSIONS
404	error response	Guild does not exist, returning UNKNOWN_GUILD

¹ A schema or parent failure returns INVALID_FORM_BODY and names the field with CATEGORIES_CANNOT_HAVE_PARENTS, INVALID_PARENT_CHANNEL, or PARENT_MUST_BE_CATEGORY. A capacity failure returns the top-level MAX_GUILD_CHANNELS or MAX_CATEGORY_CHANNELS

² The missing-authenticator code is TWO_FACTOR_REQUIRED, returned only after MANAGE_CHANNELS has been confirmed, so a caller without the permission receives 403 instead

Side effects

The operation consumes one guild channel slot and, when a parent is supplied, one slot in that category. It creates a CHANNEL_CREATE guild audit log entry with the supplied reason, plus one CHANNEL_OVERWRITE_CREATE entry for every stored overwrite, whether that overwrite was supplied or inherited. Reaching either channel limit fails the request without consuming a slot.

It emits Channel Create with the complete channel object only to sessions that can view the new channel.

Rate limit

10 requests per minute for each authenticated user and guild ID, on the guild:channel:create::guild_id bucket.

Modify guild channel positions

PATCH/v1/guilds/{guild_id}/channelsBotMFA

Applies a guild channel hierarchy update and returns 204 with an empty body. Requires MANAGE_CHANNELS at guild level. Emits one Channel Update Bulk Gateway event for each entry that changes the order.

Limitations

• Setting lock_permissions on an entry that changes the parent also requires MANAGE_ROLES in the moved channel.
• The operation records no guild audit log entry, so an X-Audit-Log-Reason header has no effect.

MANAGE_CHANNELS is an elevated permission, so it also requires an enrolled multi-factor authenticator when the guild MFA level is elevated and the caller is not the guild owner.

Concurrent hierarchy updates to the same guild can return 423 GENERAL_ERROR with a Retry-After header of two seconds.

An unknown channel, parent or sibling rejects the entire request. FiveCord applies entries one at a time. When a later entry fails a check after that existence check, including the lock_permissions authority check, every earlier entry stays applied. Moving a category moves its children with it, and neither the category nor its children count as destination siblings.

After a move, positions run consecutively from 1 across the guild. Each category is followed by its children, with text and link channels before voice channels.

A move can change other channels’ positions

Renumbering can change positions of channels not named in the request. An entry that leaves the order unchanged has no effect.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

JSON body

The top-level body is an array of channel position objects of any length, including zero. Every channel, parent, and sibling an entry names must exist in this guild. A category cannot be given a parent, and a parent that is not a category is refused. A channel cannot be positioned relative to itself or to one of its own children. Moving a channel into a full category is refused with 400 MAX_CATEGORY_CHANNELS.

Inside a category, voice channels come last

Placing a voice channel above a text or link sibling, or placing a text or link channel below a voice sibling, returns VOICE_CHANNELS_CANNOT_BE_ABOVE_TEXT_CHANNELS.

Channels at the guild root are exempt from this restriction.

Response

Status	Body	Condition
204	empty	Channel hierarchy was applied
40012	error response	An entry is structurally invalid, the destination category is full, or the caller has no enrolled authenticator in an elevated-MFA guild
403	error response	Caller lacks MANAGE_CHANNELS, is not a member of the guild, or set lock_permissions without sufficient authority in the moved channel, each returning MISSING_PERMISSIONS
404	error response	Guild does not exist, returning UNKNOWN_GUILD
423	error response	Another hierarchy update to this guild is in progress, returning GENERAL_ERROR

¹ A structural failure returns INVALID_FORM_BODY and names the field with CHANNEL_NOT_FOUND, INVALID_CHANNEL_ID, INVALID_PARENT_CHANNEL, PARENT_MUST_BE_CATEGORY, CATEGORIES_CANNOT_HAVE_PARENTS, PRECEDING_CHANNEL_MUST_SHARE_PARENT, CANNOT_POSITION_CHANNEL_RELATIVE_TO_ITSELF, or VOICE_CHANNELS_CANNOT_BE_ABOVE_TEXT_CHANNELS. A full destination category returns the top-level MAX_CATEGORY_CHANNELS

² The missing-authenticator code is TWO_FACTOR_REQUIRED, returned only after MANAGE_CHANNELS has been confirmed, so a caller without the permission receives 403 instead

Side effects

Each entry that changes the order emits Channel Update Bulk with the resulting hierarchy filtered to channels each recipient can view.

When lock_permissions copies the destination category’s overwrites, re-read the moved channel to obtain them. The copy has no Gateway event or audit entry.

The copy requires MANAGE_ROLES in the moved channel. The caller must also hold every allow bit the copy adds and every deny bit the copy removes. Insufficient authority returns 403 MISSING_PERMISSIONS, but the channel move remains applied.

Rate limit

30 requests per 10 seconds for each authenticated user and guild ID, on the guild:channel:positions::guild_id bucket.