Channels

A channel is where a conversation happens, in text or in voice. A guild owns text, announcement, voice, category, link, forum and media channels, and the threads inside them. Outside a guild, a channel is a direct message, a group direct message, or the personal notes channel.

Messages defines message content, and Guild channels defines guild-scoped listing, creation and reordering. Threads defines threads, and Forums defines forum and media channels. Calls defines ringing, the region of a private call, and ending a call. Streams defines the stream keys and previews of a Go Live screen share.

Channel object

A channel object always has its identity and type. Every other field is present only for the channel types that own it.

Structure

Field	Type	Description
id	snowflake	The ID of the channel
type	integer	The type of the channel
guild_id?	snowflake	The ID of the guild, present only for a guild channel
name?¹	string	The name of the channel, present for a guild channel and for a group direct message
topic?	?string	The topic of the channel, or null when none is set, present only for a guild text, announcement, voice, forum, or media channel
url?	?string	The destination URL, present only for a guild link channel
icon?	?string	The icon hash, present only for a group direct message
owner_id?	?snowflake	The ID of the owner, or null when the channel stores none, present only for a group direct message and a thread
position?²	integer	The sort position, present only for a guild channel other than a thread
parent_id?¹³	?snowflake	The ID of the parent category, null when the channel sits at the top level
bitrate?³	?integer	The voice bitrate in bits per second, present only for a guild voice channel
user_limit?⁴	?integer	The configured member occupancy limit, present only for a guild voice channel
voice_connection_limit?⁵	?integer	The number of simultaneous voice connections one user may hold, present only for a guild voice channel
rtc_region?⁶	?string	The ID of the selected RTC region, present only for a guild voice channel
rtc_p2p?	boolean	Whether the channel is pinned to peer-to-peer voice, present only for a guild voice channel
last_message_id?	?snowflake	The ID of the most recent message, null when the channel has none
last_pin_timestamp?	?ISO8601 timestamp	The time a message was most recently pinned, or null when nothing has ever been pinned
permission_overwrites?⁷	array[permission overwrite object]	The overwrites applied to this channel, present only for a guild channel other than a thread
recipients?⁸	array[partial user object]	The other recipients of a direct message or group direct message (max 49)
nsfw?⁹	boolean	Whether the channel has its own age restriction, present only for a guild channel other than a thread and for a group direct message, where it marks the group for mature content
nsfw_override?⁹	?boolean	Whether this channel overrides the inherited age restriction, or null when it inherits, present only for a guild channel other than a thread
content_warning_level?¹⁰	integer	The content warning level stored on this channel, present only for a guild channel other than a thread
content_warning_text?¹⁰	?string	The content warning text stored on this channel, or null when the channel inherits, present only for a guild channel other than a thread
rate_limit_per_user?¹¹	integer	The slowmode interval in seconds, present only for a thread and a text, announcement, voice, forum, or media channel
nicks?¹²	map[snowflake, string]	The group direct message nicknames keyed by the decimal user ID (each 1-32 characters)
flags?¹⁴	integer	The channel flags, present only for a forum channel, a media channel, and a thread
thread_metadata?	thread metadata object	The archive and lock state, present only for a thread
message_count?	integer	The number of messages in the thread, present only for a thread
total_message_sent?	integer	The number of messages ever sent in the thread, present only for a thread
member_count?	integer	The number of thread members, capped at 50, present only for a thread
applied_tags?¹⁵	array[snowflake]	The IDs of the forum tags applied to a post (max 5)
member_ids_preview?¹⁵	array[snowflake]	The IDs of the most recently joined members of a post, newest first (max 8)
member?¹⁶	thread member object	The thread member object of the caller
default_auto_archive_duration?¹⁷	?integer	The stored default auto archive duration, which Fluxer does not apply to a new thread, or null when none is set
default_thread_rate_limit_per_user?¹⁷	integer	The slowmode interval in seconds new threads inherit
available_tags?	array[forum tag object]	The tags a post can apply (max 20), present only for a forum or media channel
default_reaction_emoji?	?default reaction object	The reaction clients show on each post, or null when none is set, present only for a forum or media channel
default_sort_order?	?integer	The default sort order of posts, or null when none is set, present only for a forum or media channel
default_forum_layout?	integer	The default layout of posts, present only for a forum channel
default_tag_setting?	string	The default tag matching of a post search, present only for a forum or media channel

¹ Omitted when a group direct message stores no name, and never present on a direct message or on the personal notes channel

² A channel that stores no position reports 0

³ A guild voice channel that stores no bitrate reports 0

⁴ The value 0 means no occupancy limit

⁵ Defaults to 5 on a guild voice channel that stores no per-user connection limit

⁶ Null selects automatic routing. List RTC regions returns the available identifiers

⁷ Always present for a guild channel other than a thread, and empty when the channel stores no overwrite

⁸ Excludes the authenticated user, omitted entirely when no other recipient remains, and never present on the personal notes channel

⁹ A channel with no explicit override reports nsfw false and nsfw_override null

¹⁰ On a channel that inherits, content_warning_level is 0 and content_warning_text is null

¹¹ The interval is 0 when the channel configures no slowmode

¹² Omitted when the group stores no nickname. Clearing a nickname removes its key from the map

¹³ On a thread, the ID of the text, announcement, forum, or media channel the thread belongs to

¹⁴ A forum or media channel that stores no flags reports 0

¹⁵ Present only for a thread whose parent is a forum or media channel

¹⁶ Present only for a thread the caller is a member of, on the operations the thread object names

¹⁷ Always present for a forum or media channel, where an unset duration is null and an unset interval is 0. Present for a guild text or announcement channel only when the channel stores a value

A thread object is a channel object with the thread fields. Forum channel fields lists the fields of a forum or media channel.

A category owns no parent_id. A client that reads the absent key as null sees a channel whose parent was cleared.

An age restriction and a content warning both resolve through this channel first, then the parent category, and finally the guild. A category has no parent category and resolves through itself and then the guild.

Example

{
  "id": "1501314428688998182",
  "type": 0,
  "guild_id": "1501314428688990000",
  "name": "general",
  "topic": "Anything goes",
  "position": 3,
  "parent_id": "1501314428688991111",
  "permission_overwrites": [],
  "nsfw": false,
  "nsfw_override": null,
  "content_warning_level": 0,
  "content_warning_text": null,
  "rate_limit_per_user": 0,
  "last_message_id": "1501320000000000000",
  "last_pin_timestamp": null
}

Channel types

Value	Name	Description
0	GUILD_TEXT	Guild text channel
1	DM	Direct message channel between exactly two accounts
2	GUILD_VOICE	Guild voice channel, which also has messages, pins, and slowmode
3	GROUP_DM	Group direct message channel
4	GUILD_CATEGORY	Guild category, which owns no parent and no messages
5	GUILD_ANNOUNCEMENT²	Guild text channel whose messages can be published to the channels that follow it
10	ANNOUNCEMENT_THREAD³	A thread in an announcement channel, visible to everyone who can view the parent
11	PUBLIC_THREAD³	A thread visible to everyone who can view the parent
12	PRIVATE_THREAD³	A thread in a guild text channel visible to its members and to thread moderators
15	GUILD_FORUM⁴	Guild channel that holds posts and no messages of its own
16	GUILD_MEDIA⁴	Forum channel that can hide media download options
998	GUILD_LINK	Guild link channel, which has a destination URL and no messages
999	DM_PERSONAL_NOTES¹	Personal notes channel

¹ Its channel ID is exactly the owning user ID, and it has no recipient and no name. Fluxer creates it on first authenticated access

² It has the fields and the slowmode of a guild text channel. Announcement channels describes publishing and following

³ Thread types describes each type

⁴ Forums describes forum and media channels

A thread, a forum channel, and a media channel are visible to a bot and to a user session that declares the channel_threads client capability. A route that resolves one by ID returns 404 UNKNOWN_CHANNEL to every other caller unless its own entry states another result. Get channel and List guild channels return default_auto_archive_duration and default_thread_rate_limit_per_user on a guild text or announcement channel to those two callers alone. channels on Get guild has forum channels, media channels, and both fields for every caller.

Permission overwrite object

A permission overwrite changes the effective guild permissions for one role or one member in one channel. allow and deny are decimal strings because a permission mask exceeds the range a JSON number preserves. Permissions defines the individual flags.

Structure

Field	Type	Description
id¹	snowflake	The ID of the role or member
type	integer	The permission overwrite type of the identifier in `id`
allow²	decimal string	The bitfield of permissions this overwrite allows
deny²	decimal string	The bitfield of permissions this overwrite denies

¹ One identifier addresses one overwrite, so storing an overwrite for an identifier that already has one replaces it, even when the two name different types

² Every bit outside the defined permission set is discarded on write, and both fields are 0 when the overwrite grants and denies nothing

No route bounds the number of overwrites a channel stores. Modify channel and Create guild channel accept a permission_overwrites array of any length, and no limit key caps it.

Example

{
  "id": "1501314428688990000",
  "type": 0,
  "allow": "3072",
  "deny": "0"
}

Permission overwrite types

Value	Name	Description
0	ROLE	Overwrite applies to a guild role
1	MEMBER	Overwrite applies to a guild member

Content warning levels

Value	Name	Description
0	INHERIT	Inherit the content warning of the parent category and then of the guild
1	CONTENT_WARNING	Apply the content warning stored on this channel

Channel slowmode state object

The slowmode state combines the channel’s configured interval with the authenticated user’s next permitted send time.

Structure

Field	Type	Description
rate_limit_per_user	integer	The configured slowmode interval in seconds, or `0` when slowmode is disabled
retry_after_ms¹	integer	The remaining delay in milliseconds before the user can send
next_send_allowed_at¹	?ISO8601 timestamp	The next permitted send time, or null when no delay applies
can_bypass²	boolean	Whether the user bypasses slowmode through BYPASS_SLOWMODE

¹ Both report no delay in a private channel, for an interval of 0, for a bot caller, and for a caller holding BYPASS_SLOWMODE

² True only for a non-bot caller holding BYPASS_SLOWMODE in a guild channel with a non-zero interval, so a bot caller and a private channel both report false even though neither is delayed

For a forum or media channel the state reports the delay before the user can create a post.

Example

{
  "rate_limit_per_user": 10,
  "retry_after_ms": 4200,
  "next_send_allowed_at": "2026-08-31T09:14:02.000Z",
  "can_bypass": false
}

RTC region object

An RTC region names one voice routing target the deployment operates. Its identifier is the value a guild voice channel stores in rtc_region, and the name and emoji exist only for display.

Structure

Field	Type	Description
id	string	The ID of the RTC region
name	string	The name shown for the region in a client
emoji	string	The emoji the operator configured for the region

Example

{
  "id": "eu-central",
  "name": "Frankfurt",
  "emoji": "🇩🇪"
}

Followed channel object

A followed channel object names the announcement channel that was followed and the channel follower webhook that now delivers its published messages.

Structure

Field	Type	Description
channel_id	snowflake	The ID of the followed announcement channel
webhook_id	snowflake	The ID of the channel follower webhook created in the target channel

Example

{
  "channel_id": "1501314428688998182",
  "webhook_id": "1501320000000000123"
}

Channel follower stats object

The follower stats count the channels that follow one announcement channel and the guilds those channels belong to.

Structure

Field	Type	Description
channel_count	integer	The number of channels that follow the announcement channel
guild_count	integer	The number of distinct guilds those channels belong to

Example

{
  "channel_count": 12,
  "guild_count": 9
}

Get channel

GET/v1/channels/{channel_id}

Bot

Returns the channel object visible to the authenticated user.

Limitations

A guild channel requires VIEW_CHANNEL, and a satisfied age verification when it resolves to an age restriction.
A thread requires VIEW_CHANNEL in its parent, and a private thread also requires membership or thread moderator status.
A private channel requires current recipient access.
The personal notes channel requires ownership.

Fluxer enforces age verification only for a guild text, announcement, voice, link, forum, or media channel, and for a thread through its parent. Fluxer never requires age verification for a guild category, even when the category has the override its children inherit.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the channel to return

Response

Status	Body	Condition
200	channel object	Channel was returned
403	error response	Caller is not a guild member or lacks `VIEW_CHANNEL`, each returning `MISSING_PERMISSIONS`
403	error response	Caller lacks `VIEW_CHANNEL` in the parent of a thread, or cannot view a private thread, each returning `MISSING_ACCESS`
403	error response	The guild exists but the caller’s membership state cannot be resolved and the request returns `ACCESS_DENIED`
403	error response	The resolved age restriction is not satisfied and the request returns `NSFW_CONTENT_AGE_RESTRICTED`
404	error response	Channel does not exist, or the caller is not a recipient of the private channel, each returning `UNKNOWN_CHANNEL`, or the guild that owns the channel does not exist and the request returns `UNKNOWN_GUILD`

Side effects

Requesting the personal notes channel of the authenticated user creates it when it does not already exist, and returns it with no Channel Create Dispatch.

Rate limit

100 requests per 10 seconds for each authenticated user and channel ID, on the channel:read::channel_id bucket.

Get channel slowmode state

GET/v1/channels/{channel_id}/slowmode

Bot

Returns the authenticated user’s channel slowmode state object. The caller needs the same access as Get channel.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the channel whose slowmode state is returned

Response

Status	Body	Condition
200	channel slowmode state object	State was returned
403	error response	Caller is not a guild member or lacks `VIEW_CHANNEL`, each returning `MISSING_PERMISSIONS`
403	error response	Caller lacks `VIEW_CHANNEL` in the parent of a thread, or cannot view a private thread, each returning `MISSING_ACCESS`
403	error response	The guild exists but the caller’s membership state cannot be resolved and the request returns `ACCESS_DENIED`
403	error response	The resolved age restriction is not satisfied and the request returns `NSFW_CONTENT_AGE_RESTRICTED`
404	error response	Channel does not exist, or the caller is not a recipient of the private channel, each returning `UNKNOWN_CHANNEL`, or the guild that owns the channel does not exist and the request returns `UNKNOWN_GUILD`

Side effects

The read does not advance the caller’s slowmode countdown. Requesting the personal notes channel of the authenticated user creates it when it does not already exist, with no Channel Create Dispatch.

Rate limit

100 requests per 10 seconds for each authenticated user and channel ID, on the channel:read::channel_id bucket.

List RTC regions

GET/v1/channels/{channel_id}/rtc-regions

Returns the RTC region objects the authenticated user can select for a guild voice channel, in ascending display name order. User-only.

Limitations

The caller needs the same access as Get channel.
The channel must be a guild voice channel.

Only regions available to the caller are returned. The array can be empty.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the guild voice channel

Response

Status	Body	Condition
200	array[RTC region object]	Available regions were returned
400	error response	Channel is not a guild voice channel and the request returns `INVALID_CHANNEL_TYPE`
403	error response	Caller is a bot or uses an OAuth2 bearer credential, or the guild exists but the caller’s membership state cannot be resolved, each returning `ACCESS_DENIED`
403	error response	The caller is not a guild member or lacks `VIEW_CHANNEL` and the request returns `MISSING_PERMISSIONS`
403	error response	The resolved age restriction is not satisfied and the request returns `NSFW_CONTENT_AGE_RESTRICTED`
404	error response	Channel does not exist and the request returns `UNKNOWN_CHANNEL`, or the guild that owns the channel does not exist and the request returns `UNKNOWN_GUILD`

Rate limit

100 requests per 10 seconds for each authenticated user and channel ID, on the channel:read::channel_id bucket.

Modify channel

PATCH/v1/channels/{channel_id}

Bot Audit reason

Modifies a guild channel or a group direct message and returns the updated channel object. Emits a Channel Update Gateway event.

Modify thread describes this route for a thread.

Limitations

A guild channel requires VIEW_CHANNEL and MANAGE_CHANNELS in that channel.
Supplying permission_overwrites also requires MANAGE_ROLES in that channel.
Supplying rtc_region on a guild voice channel also requires UPDATE_RTC_REGION.
A caller who is not the guild owner cannot allow a permission bit outside their own effective permissions in that channel, and cannot remove a denied bit outside them either.
A group direct message requires the caller to be a current recipient.
Ownership transfer requires the caller to be the current owner, and so does setting another recipient’s nickname or clearing every nickname.

MANAGE_CHANNELS and MANAGE_ROLES are elevated permissions. Each also requires an enrolled multi-factor authenticator when the guild MFA level is elevated and the caller is not the guild owner. A caller who holds the permission without that authenticator receives 400 TWO_FACTOR_REQUIRED.

Set channel permission overwrite and Delete channel permission overwrite each change one overwrite and leave the rest untouched.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the channel to modify

Request headers

Field	Type	Description
X-Fluxer-Features?¹	string	A comma-separated feature declaration

¹ Read only when permission_overwrites is supplied. A feature-gated bit the declaration does not name is copied from the stored overwrite

JSON body

The stored channel type selects the body variant. A direct message and the personal notes channel match no variant, and Fluxer rejects both with 400 INVALID_FORM_BODY. A thread accepts every field of the Modify thread body.

Guild channel body

Every field is optional, and an omitted field preserves its current value. Every guild channel type other than a thread accepts the fields below, and a field the stored type does not own is accepted and discarded.

Field	Type	Description
name?¹	?string	The name of the channel (1-100 characters after normalisation)
topic?²	?string	The topic of the channel (1-1,024 characters), or null to clear it
url?³	?string	The destination of a guild link channel (1-2,048 characters, `http` or `https`), or null to clear it
parent_id?⁴	?snowflake	The ID of the parent category, where null or the snowflake `0` moves the channel to the top level
bitrate?⁵¹³	?integer	The voice bitrate in bits per second (8,000-384,000)
user_limit?⁵	?integer	The voice occupancy limit (0-99, where `0` configures no limit)
voice_connection_limit?⁵	?integer	The number of simultaneous voice connections one user may hold (1-100)
permission_overwrites?⁶	array[permission overwrite object]	The complete overwrite collection that replaces the stored one
nsfw_override?⁷	?boolean	Whether this channel overrides the inherited age restriction
nsfw?⁸	?boolean	Whether the channel is age restricted, a legacy switch superseded by `nsfw_override`
content_warning_level?⁹	integer	The content warning level to store on this channel
content_warning_text?¹⁰	?string	The content warning text (max 200 characters)
rate_limit_per_user?¹¹	?integer	The slowmode interval in seconds (0-21,600)
rtc_region?¹²	?string	The ID of the RTC region (1-64 characters) for a guild voice channel, where null selects automatic routing
rtc_p2p?	boolean	Whether to pin a guild voice channel to peer-to-peer voice. Ignored on every other channel type

¹ An explicit null preserves the current name. In a guild without flexible channel names, Fluxer lowercases a guild text, announcement, forum, or media channel name, replaces its whitespace with hyphens, and removes disallowed punctuation

² An explicit null clears the stored topic. A forum or media channel accepts 1-4,096 characters

³ Applied only to a guild link channel. An explicit null clears the destination

⁴ A category rejects any parent with CATEGORIES_CANNOT_HAVE_PARENTS

⁵ Applied only to a guild voice channel, and an explicit null clears the stored value

⁶ Each entry has id, type, and the optional allow and deny masks, each defaulting to 0

⁷ An explicit null returns the channel to inheriting from its parent category and then its guild

⁸ nsfw_override wins when both are supplied. Alone, true maps to nsfw_override true and false maps to null

⁹ Only 0 and 1 are accepted, and 0 returns the channel to inheriting

¹⁰ Trimmed. A value empty after trimming, or an explicit null, clears the stored text

¹¹ Applied only to a guild text, announcement, voice, forum, or media channel. An explicit null preserves the current interval

¹² Applied only to a guild voice channel. Supplying the field at all, including as null, requires UPDATE_RTC_REGION

¹³ The stored value is capped at 96,000 unless the guild holds an audio bitrate feature. A higher value is stored at the cap

A guild text or announcement channel also accepts type, which converts a text channel into an announcement channel or back.

Field	Type	Description
type?¹⁴	integer	The channel type to convert to, either `0` or `5`

¹⁴ Absent, null, or equal to the stored type keeps the type. A value other than 0 or 5 returns 400 CHANNEL_TYPE_CONVERSION_NOT_SUPPORTED. Every other stored type ignores type

Converting a text channel into an announcement channel fails with 400 CHANNEL_HAS_FOLLOWED_CHANNELS while the text channel receives messages from any followed announcement channel. Delete its channel follower webhooks first. The conversion also fails with 400 CHANNEL_HAS_THREADS while the text channel holds a private thread. A conversion changes the type of the public threads of the channel as Thread types describes. Converting an announcement channel back into a text channel needs no preparation, and Fluxer removes every follow of it afterwards.

A guild text, announcement, forum, or media channel also accepts these fields.

Field	Type	Description
default_auto_archive_duration?¹⁵	?integer	The stored default auto archive duration, which Fluxer does not apply to a new thread, or null to clear it
default_thread_rate_limit_per_user?¹⁵	?integer	The slowmode interval in seconds new threads inherit (0-21,600), or null to clear it

¹⁵ Fluxer discards both fields from a caller other than a bot or a user session that declares channel_threads

A forum channel also accepts every field of the forum field table. A media channel accepts every field of the forum field table except default_forum_layout.

A url that is not an absolute http or https URL with a host returns 400 INVALID_FORM_BODY with the code INVALID_URL_FORMAT on the path url.

A parent that does not exist in the same guild returns 400 INVALID_FORM_BODY with the code INVALID_PARENT_CHANNEL on the path parent_id. A parent that is not a category returns PARENT_MUST_BE_CATEGORY the same way.

Naming a category other than the current parent also checks capacity. A full category returns 400 MAX_CATEGORY_CHANNELS with the ceiling it reached, which is the deployment’s max_channels_per_category limit and defaults to 50.

Fluxer accepts an overwrite mask as a decimal string or as a JSON integer. The decimal string holds at most 9223372036854775807, and a larger one returns 400 INVALID_FORM_BODY with the code INTEGER_OUT_OF_INT64_RANGE. The JSON integer holds at most 9007199254740991, and a number outside the safe integer range returns INVALID_INTEGER_FORMAT. Every bit outside the defined permission set is discarded.

A non-null rtc_region names a region List RTC regions returns for this guild. Any other value returns 400 INVALID_FORM_BODY with the code INVALID_OR_RESTRICTED_RTC_REGION on the path rtc_region. A deployment that configures no voice topology validates no region and stores any accepted string.

Group direct message body

Every field is optional, and an omitted field preserves its current value.

Field	Type	Description
name?	?string	The name of the group (1-100 characters after normalisation), or null to clear it
icon?¹	?base64 string	The base64-encoded icon image (at most 139,810,136 encoded characters), or null to clear it
owner_id?²	?snowflake	The ID of the new owner
nicks?³	?map[snowflake, ?string]	The nicknames keyed by the decimal user ID (each 0-32 characters, or null)
nsfw?⁴	?boolean	Whether the group is marked for mature content

¹ Raw base64 or a data URL, with 1 through 139,810,136 characters after the prefix

² An explicit null requests no transfer. The caller must be the current owner and the target a current recipient

³ An explicit null clears every nickname and requires ownership. A non-owner may address only their own key

⁴ An explicit null leaves the setting unchanged. Changing the value requires ownership

Decoded icon bytes are at most the instance-configured avatar_max_size limit, which defaults to the 10 MiB ceiling of 10485760 bytes. A larger image is rejected on the path icon with the code IMAGE_SIZE_EXCEEDS_LIMIT. PNG, JPEG, WebP, GIF, APNG, AVIF, HEIC, HEIF, JXL, and SVG are accepted, and an animated AVIF is rejected on the same path with INVALID_IMAGE_FORMAT.

An owner_id naming an account that is not a current recipient returns 404 UNKNOWN_USER. A bot target returns 400 CANNOT_TRANSFER_OWNERSHIP_TO_BOT.

Fluxer trims a stored nickname, and a value that is null or empty after trimming clears that one nickname. A nicks key that is neither a current recipient nor the caller returns 404 UNKNOWN_USER.

A group marked for mature content accepts media the scanner flags as sensitive, like an age-restricted guild channel. Turning nsfw on while any recipient fails the age check returns 400 GROUP_DM_MATURE_CONTENT_INELIGIBLE, which does not say which recipient. A user who fails the age check cannot be added to a marked group, and the add returns the same 403 MISSING_ACCESS as a rejecting admission policy.

Response

Status	Body	Condition
200	channel object	Channel was modified, or the submitted values already matched the stored state
400	error response	The `type` on a text or announcement channel is neither `0` nor `5`, returning `CHANNEL_TYPE_CONVERSION_NOT_SUPPORTED`
400	error response	The text channel receives followed channels, returning `CHANNEL_HAS_FOLLOWED_CHANNELS`
400	error response	The text channel holds a private thread, returning `CHANNEL_HAS_THREADS`
400	error response	`nsfw` is turned on while a recipient fails the age check, returning `GROUP_DM_MATURE_CONTENT_INELIGIBLE`
403	error response	A required permission, ownership, or permission bit authority is absent and the request returns `MISSING_PERMISSIONS`
403	error response	A concurrent change removed the caller from the group direct message and the request returns `MISSING_ACCESS`
403	error response	The guild exists but the caller’s membership state cannot be resolved and the request returns `ACCESS_DENIED`
403	error response	The resolved age restriction is not satisfied and the request returns `NSFW_CONTENT_AGE_RESTRICTED`
404	error response	Channel does not exist, or the caller is not a recipient of the group direct message, each returning `UNKNOWN_CHANNEL`
404	error response	The guild that owns the channel does not exist and the request returns `UNKNOWN_GUILD`
404	error response	A referenced owner or nickname target is not a current recipient and the request returns `UNKNOWN_USER`
429	error response	A concurrent follow holds the channel, returning `RESOURCE_LOCKED`

Side effects

A guild channel change emits Channel Update to every session subscribed to its guild. For a forum or media channel the event reaches only a session with thread access. Replacing a category’s permission overwrites also replaces them on each child whose overwrites still exactly match the category’s previous values, with one Dispatch per changed child. A child whose overwrites had differed is left unchanged.

Changing rate_limit_per_user clears the remaining slowmode delay of every user in the channel. Each user’s next message is then checked against the new interval. Changing rtc_region on a guild voice channel moves its active voice connections to the selected region. A peer-to-peer call in the channel moves to a voice server with that change, unless the channel stores rtc_p2p true. Changing rtc_p2p leaves a running call as it is and applies to the next call that starts after the channel empties. Changing it to true fails with the field code GUILD_FEATURE_NOT_TOGGLEABLE unless the caller’s peer-to-peer voice assignment is enabled.

Converting an announcement channel into a text channel deletes every channel follower webhook that follows it. The deletion runs in the background after the response, emits Webhooks Update for each target channel, and writes no audit log entry. Copies already delivered stay in the target channels, and later edits and deletions of the published messages still reach them.

A request that changes at least one field creates a channel update audit log entry with the supplied reason, and a conversion records the type change in it. Supplying permission_overwrites also creates one overwrite create, update, or delete audit log entry for each overwrite the array adds, changes, or removes.

A group direct message change emits Channel Update to every current recipient. A name or successful icon change creates a system message delivered with Message Create, and replacing the icon permanently deletes the previous one. Ownership and nickname changes create no system message and no audit entry.

Rate limit

20 requests per 10 seconds for each authenticated user and channel ID, on the channel:update::channel_id bucket.

Delete or leave channel

DELETE/v1/channels/{channel_id}

Bot Audit reason

Deletes a guild channel, closes a direct message, or removes the caller from a group direct message. Returns 204 with an empty body. Emits a Channel Delete Gateway event.

Delete thread describes this route for a thread.

Limitations

Deleting a guild channel requires VIEW_CHANNEL and MANAGE_CHANNELS.
Closing a direct message or leaving a group direct message requires current recipient access.
The personal notes channel cannot be deleted, and the request returns 400 CANNOT_EXECUTE_ON_DM.
Setting delete_messages also requires sudo mode for a user session, satisfied by a valid sudo proof or by the verification fields in the body. A bot token always satisfies it.

MANAGE_CHANNELS is an elevated permission. It also requires an enrolled multi-factor authenticator when the guild MFA level is elevated and the caller is not the guild owner. A caller who holds the permission without that authenticator receives 400 TWO_FACTOR_REQUIRED. The sudo requirement on delete_messages applies at every guild MFA level.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the channel to delete, close, or leave

Query parameters

Field	Type	Description
silent?¹	boolean	Whether to suppress the leave system message of a group direct message (default false)
delete_messages?¹	boolean	Whether to delete the caller’s own messages in this channel first (default false)

¹ Only the exact trimmed values true, True, and 1 are true. An absent parameter and every other value, including TRUE and yes, are false

Request headers

Field	Type	Description
X-Fluxer-Sudo-Mode-JWT?¹	string	An existing sudo mode proof, read when `delete_messages` is set

¹ An accepted proof is echoed back in the same response header, and completing the MFA path issues a fresh one

JSON body

The body is optional. Fluxer reads it only when delete_messages is set and no existing sudo proof satisfies the requirement.

Field	Type	Description
password?¹	string	The account password, offered as the sudo proof
mfa_method?²	string	The verification method, either `totp` or `webauthn`
mfa_code?	string	The authenticator code or an unconsumed backup code (1-32 characters), supplied with the `totp` method
webauthn_response?	WebAuthn assertion object	The WebAuthn assertion for sudo verification
webauthn_challenge?	string	The challenge (1-256 characters) bound to the sudo mode assertion

¹ Accepted only for an account holding no TOTP secret and no registered WebAuthn credential. A rejected password returns 400 INVALID_FORM_BODY with the code INVALID_PASSWORD on the path password

² Accepted only for an account holding a TOTP secret or a registered WebAuthn credential. The totp method reads mfa_code as a backup code alone while the account holds no TOTP secret. A rejected code or assertion returns 400 INVALID_FORM_BODY with the code INVALID_MFA_CODE on the path mfa_code

An account that stores no password, no TOTP secret, and no registered WebAuthn credential is verified without any proof.

Response

Status	Body	Condition
204	empty	Channel was deleted, closed, or left
400	error response	Target is the personal notes channel and the request returns `CANNOT_EXECUTE_ON_DM`
403	error response	Caller is not a guild member or lacks `VIEW_CHANNEL` or `MANAGE_CHANNELS`, each returning `MISSING_PERMISSIONS`
403	error response	Sudo verification is required and the request returns `SUDO_MODE_REQUIRED`
403	error response	A concurrent change removed the caller from the group direct message and the request returns `MISSING_ACCESS`
403	error response	The guild exists but the caller’s membership state cannot be resolved and the request returns `ACCESS_DENIED`
403	error response	The resolved age restriction is not satisfied and the request returns `NSFW_CONTENT_AGE_RESTRICTED`
404	error response	Channel does not exist, or the caller is not a recipient of the private channel, each returning `UNKNOWN_CHANNEL`, or the guild that owns the channel does not exist and the request returns `UNKNOWN_GUILD`

Side effects

Deleting a guild category first clears the parent_id of every child channel and emits Channel Update for each one. The category itself is then deleted like any other guild channel.

Deleting a guild channel permanently removes its messages, attachments, invites and webhooks.

Deleting a guild text, announcement, forum, or media channel also deletes every thread in it with its messages, attachments, and memberships. The deletion runs in the background after the response. Fluxer emits no Thread Delete for those threads and writes no audit log entry for them. A client removes every thread whose parent_id is the channel when it receives Channel Delete.

Deleting an announcement channel also deletes every channel follower webhook that follows it and turns each copy of its published messages into a deleted-source placeholder, both in the background after the response. Guild subscribers receive Channel Delete, and the deletion appears in the audit log. When the deleted channel is the guild’s system, rules or AFK channel, Fluxer clears that guild setting and emits Guild Update.

Closing a direct message marks the channel closed for the caller alone and emits Channel Delete to that caller. The channel, its messages, and the other recipient’s view are untouched.

Leaving a group direct message removes the caller from the recipient set, removes the caller’s nickname, and closes the channel for the caller. If the caller owned the group, ownership transfers to one of the remaining recipients chosen at random.

Remaining recipients receive Channel Recipient Remove, and unless silent is true also a removal system message through Message Create. The leaving caller receives Channel Delete. No Channel Update reports the ownership transfer or the removed nickname, so a client tracking owner_id or nicks must refetch the channel.

Leaving as the final recipient permanently deletes the channel’s messages and the channel record, with no system message.

Setting delete_messages deletes the caller’s authored messages in this channel after sudo verification and before the channel operation runs, and the response waits for that deletion to finish.

Rate limit

20 requests per 10 seconds for each authenticated user and channel ID, on the channel:delete::channel_id bucket.

Add group direct message recipient

PUT/v1/channels/{channel_id}/recipients/{user_id}

Bot

Adds a user to a group direct message and returns 204 with an empty body. Emits a Channel Recipient Add Gateway event.

Limitations

The caller must be a current recipient of the group, and must be friends with the target, including when the caller is a bot.
The target’s group direct message admission policy must allow the caller.
A solved CAPTCHA challenge is required while the instance check is on.

Fluxer evaluates the target’s admission policy in this order.

A target that has never stored settings admits every caller.
The nobody setting rejects every caller, and the everyone setting admits every caller.
The friends-only setting admits only a caller the target has as a friend.
Otherwise Fluxer admits the caller through an existing friendship, then through a mutual friend when the friends-of-friends setting is enabled, and then through a mutual guild when the guild-members setting is enabled.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the group direct message channel
user_id	snowflake	The ID of the user to add

Request headers

Field	Type	Description
X-Captcha-Token?¹	string	The solved ALTCHA challenge, see CAPTCHA handling

¹ A missing token returns 400 CAPTCHA_REQUIRED and a rejected token returns 400 INVALID_CAPTCHA, each with a new challenge. CAPTCHA handling states when an instance skips verification

Response

Status	Body	Condition
204	empty	Recipient was added, or was already a recipient
400	error response	CAPTCHA proof is missing or rejected, or the caller and target are not friends and the request returns `NOT_FRIENDS_WITH_USER`
400	error response	The group is already full and the request returns `MAX_GROUP_DM_RECIPIENTS`
400	error response	The channel is not a group direct message and the request returns `INVALID_CHANNEL_TYPE`
403	error response	Caller is not a recipient, the target’s admission policy rejects the caller, or the target fails the age check of a group marked for mature content, each returning `MISSING_ACCESS`
403	error response	The account is limited and the request returns `ACCOUNT_LIMITED`
404	error response	Channel does not exist and the request returns `UNKNOWN_CHANNEL`

The MAX_GROUP_DM_RECIPIENTS body has max_recipients, the exact ceiling that was reached. That ceiling is the deployment’s max_group_dm_recipients limit resolved for the caller, and it defaults to 50.

Side effects

The added user receives Channel Create, existing recipients receive Channel Recipient Add, and every recipient receives an addition system message through Message Create. Adding an existing recipient changes nothing and emits no Dispatch.

Rate limit

20 requests per 10 seconds for each authenticated user and channel ID, on the channel:update::channel_id bucket. The user:group_dm:recipient:add protection bucket adds 10 requests per hour for each authenticated user, and does not consume the global limit.

Remove group direct message recipient

DELETE/v1/channels/{channel_id}/recipients/{user_id}

Bot

Removes a user from a group direct message and returns 204 with an empty body. Emits a Channel Recipient Remove Gateway event.

Limitations

The caller must be a current recipient.
A caller may remove themselves regardless of ownership.
Removing another recipient requires ownership of the group.
Setting delete_messages takes effect only when user_id is the caller, and it then requires sudo verification on the same terms as Delete or leave channel.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the group direct message channel
user_id	snowflake	The ID of the recipient to remove

Query parameters

Field	Type	Description
silent?¹	boolean	Whether to suppress the recipient removal system message (default false)
delete_messages?¹	boolean	Whether to delete the caller’s own messages in this channel before self-removal (default false)

¹ Only the exact trimmed values true, True, and 1 are true. An absent parameter and every other value, including TRUE and yes, are false

Request headers

Field	Type	Description
X-Fluxer-Sudo-Mode-JWT?¹	string	An existing sudo mode proof, read when `delete_messages` is set for self-removal

¹ An accepted proof is echoed back in the same response header, and completing the MFA path issues a fresh one

JSON body

The optional body has the same sudo verification fields as Delete or leave channel. Fluxer reads it only when a self-removal sets delete_messages and the request has no existing sudo proof.

Response

Status	Body	Condition
204	empty	Recipient was removed
400	error response	Channel is not a group direct message and the request returns `INVALID_CHANNEL_TYPE`
400	error response	The target is not a recipient and the request returns `INVALID_FORM_BODY` with the code `USER_NOT_IN_CHANNEL`
403	error response	Caller is not a recipient and the request returns `MISSING_ACCESS`
403	error response	The caller is not the owner while removing another recipient and the request returns `MISSING_PERMISSIONS`
403	error response	Sudo verification is required and the request returns `SUDO_MODE_REQUIRED`
404	error response	Channel does not exist and the request returns `UNKNOWN_CHANNEL`

Side effects

Removal closes the channel for the recipient and clears their nickname. If they owned the group, ownership transfers to a randomly selected remaining recipient, as for Delete or leave channel.

The removed recipient receives Channel Delete. Remaining recipients receive Channel Recipient Remove, and the removal system message through Message Create unless silent is true. No Channel Update reports the ownership transfer or the removed nickname.

Removing the final recipient permanently deletes the channel’s messages, removes them from search, and deletes the channel record, with no system message. Setting delete_messages on a self-removal deletes the caller’s messages in this channel before the removal runs.

Rate limit

20 requests per 10 seconds for each authenticated user and channel ID, on the channel:update::channel_id bucket.

Set channel permission overwrite

PUT/v1/channels/{channel_id}/permissions/{overwrite_id}

Bot Audit reason

Creates or replaces one permission overwrite on a guild channel and returns 204 with an empty body. Requires MANAGE_ROLES in that channel. Emits a Channel Update Gateway event.

Limitations

A caller without ADMINISTRATOR cannot allow a permission bit outside their own effective permissions in that channel, and cannot remove a denied bit outside them either.
A thread has no permission overwrites, as Thread permissions describes.

The operation does not require VIEW_CHANNEL and never returns TWO_FACTOR_REQUIRED or NSFW_CONTENT_AGE_RESTRICTED.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the guild channel
overwrite_id	snowflake	The ID of the role or member the overwrite represents

Request headers

Field	Type	Description
X-Fluxer-Features?¹	string	A comma-separated feature declaration

¹ A feature-gated bit the declaration does not name is copied from the stored overwrite, so the request can neither set nor clear it

JSON body

Field	Type	Description
type¹	integer	The permission overwrite type of `overwrite_id`
allow?²	?decimal string	The bitfield of permissions to allow (default `0`)
deny?²	?decimal string	The bitfield of permissions to deny (default `0`)

¹ Only 0 and 1 are accepted

² A decimal string of at most 9223372036854775807, or a JSON integer of at most 9007199254740991. An omitted or null value is treated as 0

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. Every bit outside the defined permission set is discarded before the authority check and before the change is applied.

Response

Status	Body	Condition
204	empty	Overwrite was created or replaced
400	error response	Channel is a thread and the request returns `INVALID_CHANNEL_TYPE`
403	error response	`MANAGE_ROLES` in the channel or permission bit authority is absent, each returning `MISSING_PERMISSIONS`
404	error response	Channel does not exist, or is not a guild channel, each returning `UNKNOWN_CHANNEL`

Side effects

Fluxer emits Channel Update to every session subscribed to the guild, including when the submitted overwrite exactly matches the stored one. When the channel is a category, every child whose overwrites exactly matched the category’s previous values receives a copy of the category’s new overwrites and its own Channel Update.

The operation records an overwrite create or update audit entry with the supplied reason. An unchanged overwrite records no audit entry.

Rate limit

20 requests per 10 seconds for each authenticated user and channel ID, on the channel:update::channel_id bucket.

Delete channel permission overwrite

DELETE/v1/channels/{channel_id}/permissions/{overwrite_id}

Bot Audit reason

Deletes one permission overwrite from a guild channel and returns 204 with an empty body. Requires MANAGE_ROLES in that channel. Emits a Channel Update Gateway event.

Limitations

A caller without ADMINISTRATOR must already hold every permission bit the removed overwrite denied.
A thread has no permission overwrites, as Thread permissions describes.

The operation is idempotent, does not require VIEW_CHANNEL, and never returns TWO_FACTOR_REQUIRED or NSFW_CONTENT_AGE_RESTRICTED.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the guild channel
overwrite_id¹	snowflake	The ID of the role or member the overwrite represents

¹ The identifier alone selects the overwrite, and the request has no overwrite type

Response

Status	Body	Condition
204	empty	Overwrite was deleted, or no overwrite existed for the identifier
400	error response	Channel is a thread and the request returns `INVALID_CHANNEL_TYPE`
403	error response	`MANAGE_ROLES` in the channel or permission bit authority is absent, each returning `MISSING_PERMISSIONS`
404	error response	Channel does not exist, or is not a guild channel, each returning `UNKNOWN_CHANNEL`

Side effects

Fluxer emits Channel Update to every session subscribed to the guild, including when the identifier names no existing overwrite. Removing an overwrite that exists also records an overwrite delete audit entry with the previous overwrite state and the supplied reason. An identifier that names no existing overwrite records no audit entry. When the target channel is a category, each child whose overwrites exactly matched the category’s previous overwrites receives a copy of the category’s new overwrites and its own Channel Update.

Rate limit

20 requests per 10 seconds for each authenticated user and channel ID, on the channel:update::channel_id bucket.

Follow announcement channel

POST/v1/channels/{channel_id}/followers

Bot Audit reason

Follows an announcement channel into a guild text channel and returns a followed channel object. Fluxer creates a channel follower webhook in the target channel, and every message later published in the announcement channel is copied into the target through it. Announcement channels describes delivery.

Limitations

The caller needs VIEW_CHANNEL on the announcement channel, and a satisfied age verification when it resolves to an age restriction.
The target must be a guild text channel in any guild, including the announcement channel’s own guild.
The caller needs MANAGE_WEBHOOKS at guild level in the target guild, and VIEW_CHANNEL and MANAGE_WEBHOOKS in the target channel.
A target channel follows one announcement channel at most once.
The guild that owns the announcement channel must not have ANNOUNCEMENT_CHANNELS_DISABLED.

MANAGE_WEBHOOKS is an elevated permission. In a target guild whose MFA level is elevated, a caller who is neither its owner nor enrolled in multi-factor authentication receives 400 TWO_FACTOR_REQUIRED.

Fluxer resolves the age restriction and the content warning of both channels through the channel, then its parent category, and then its guild. An age-restricted announcement channel can only be followed into an age-restricted target. An announcement channel with a content warning can only be followed into a target that has a content warning or an age restriction.

An announcement channel has no cap on its follows. The follower webhook takes one slot of the target’s max_webhooks_per_channel and max_webhooks_per_guild allowances, which default to 15 and 1000.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the announcement channel to follow

JSON body

Field	Type	Description
webhook_channel_id	snowflake	The ID of the guild text channel that receives published messages

Response

Status	Body	Condition
200	followed channel object	The follow was created
400	error response	The followed channel is not an announcement channel, returning `ANNOUNCEMENT_CHANNEL_REQUIRED`
400	error response	The target is not a guild text channel, returning `INVALID_FOLLOW_TARGET_CHANNEL`
400	error response	The target already follows this announcement channel, returning `CHANNEL_ALREADY_FOLLOWED`
400¹	error response	The target does not meet the age restriction or content warning rule
400²	error response	The webhook allowance of the target is already reached
400	error response	The caller holds `MANAGE_WEBHOOKS` with no enrolled authenticator in an elevated-MFA guild
403	error response	A permission on either channel is absent, returning `MISSING_PERMISSIONS`
403	error response	The resolved age restriction is not satisfied, returning `NSFW_CONTENT_AGE_RESTRICTED`
403	error response	The source guild has `ANNOUNCEMENT_CHANNELS_DISABLED`, returning `FEATURE_TEMPORARILY_DISABLED`
403	error response	The generated webhook name is blocked, returning `CONTENT_BLOCKED`
404	error response	Either channel does not exist, returning `UNKNOWN_CHANNEL`
429	error response	A concurrent follow or conversion holds the target channel, returning `RESOURCE_LOCKED`

¹ FOLLOW_TARGET_NOT_AGE_RESTRICTED for an age-restricted announcement channel, and FOLLOW_TARGET_CONTENT_WARNING_REQUIRED for one with a content warning

² MAX_WEBHOOKS_PER_CHANNEL or MAX_WEBHOOKS_PER_GUILD, each with the allowance that was reached

Side effects

The follow creates a channel follower webhook in the target channel. Its name is the source guild name and the announcement channel name, as in Fluxer #updates, cut to 80 characters. When that name fails validation or the blocklist scan, Fluxer uses the channel name alone. The webhook avatar is a copy of the source guild icon at the time of the follow, or null when the source guild has no icon. It does not change when the source guild icon changes, and Update webhook cannot replace it. A member who manages the target channel’s webhooks can rename it later. Each copy uses the source guild icon at the time of delivery as its author avatar.

It emits Webhooks Update for the target channel, records a WEBHOOK_CREATE audit log entry in the target guild with the supplied reason, and posts a CHANNEL_FOLLOW_ADD system message in the target channel through Message Create. The follow takes effect for messages published after it, and earlier messages are never copied.

Delete webhook on the follower webhook removes the follow.

Rate limit

5 requests per 10 seconds for each authenticated user and channel ID, on the channel:follow::channel_id bucket.

Get channel follower stats

GET/v1/channels/{channel_id}/follower-stats

Bot

Returns the channel follower stats object of an announcement channel. The caller needs the same access as Get channel.

The counts are cached for 60 seconds, so a follow or unfollow can take up to a minute to show.

Path parameters

Field	Type	Description
channel_id	snowflake	The ID of the announcement channel

Response

Status	Body	Condition
200	channel follower stats object	Counts were returned
400	error response	The channel is not an announcement channel, returning `ANNOUNCEMENT_CHANNEL_REQUIRED`
403	error response	Caller is not a guild member or lacks `VIEW_CHANNEL`, each returning `MISSING_PERMISSIONS`
403	error response	The resolved age restriction is not satisfied, returning `NSFW_CONTENT_AGE_RESTRICTED`
404	error response	Channel does not exist, returning `UNKNOWN_CHANNEL`

Rate limit

10 requests per 10 seconds for each authenticated user and channel ID, on the channel:follower_stats::channel_id bucket.