Channels Resource

Channels are the primary way users interact with Discord. All conversations, whether over text or voice, in guilds or a group, happen in channels.

Channel Object

A guild or private channel within Discord.

Channel Structure
FieldTypeDescription
idsnowflakeThe ID of the channel
typeintegerThe type of channel
guild_id?snowflakeThe ID of the guild the channel is in
position?integerSorting position of the channel
permission_overwrites?array[permission overwrite object]Explicit permission overwrites for members and roles
name??stringThe name of the channel (1-100 characters)
topic??stringThe channel topic (max 4096 characters for thread-only channels, max 1024 characters otherwise)
nsfw?booleanWhether the channel is NSFW
last_message_id??snowflakeThe ID of the last message sent (or thread created for thread-only channels, guild added for directory channels) in this channel (may not point to an existing resource)
bitrate?integerThe bitrate (in bits) of the voice channel
user_limit? 1integerThe user limit of the voice channel (max 99, 0 refers to no limit)
rate_limit_per_user? 2integerDuration in seconds seconds a user has to wait before sending another message (max 21600); bots, as well as users with the permission MANAGE_MESSAGES or MANAGE_CHANNELS, are unaffected
recipients?array[user object]The recipients of the private channel, excluding the requesting user
recipient_flags? 3integerThe recipient flags of the DM
icon??stringThe group DM's icon hash
managed?booleanWhether the group DM is managed by an application
application_id?snowflakeThe ID of the application that manages the group DM
owner_id?snowflakeThe ID of the owner of the group DM or thread
owner??guild member objectThe owner of this thread; only included on certain API endpoints
parent_id??snowflakeThe ID of the parent category/channel for the guild channel/thread
last_pin_timestamp??ISO8601 timestampWhen the last pinned message was pinned, if any
rtc_region??stringThe voice region ID for the voice channel (automatic when null)
video_quality_mode?integerThe camera video quality mode of the voice channel (default AUTO)
total_message_sent?integerThe number of messages ever sent in a thread; similar to message_count on message creation, but will not decrement the number when a message is deleted
message_count?integerThe number of messages (not including the initial message or deleted messages) in a thread (if the thread was created before July 1, 2022, it stops counting at 50)
member_count?integerAn approximate count of users in a thread, stops counting at 50
member_ids_preview?array[snowflake]The IDs of some of the members in a thread
thread_metadata?thread metadata objectThread-specific channel metadata
member?thread member objectThread member object for the current user, if they have joined the thread; only included on certain API endpoints
default_auto_archive_duration? 4?integerDefault duration in minutes for newly created threads to stop showing in the channel list after inactivity (one of 60, 1440, 4320, 10080)
default_thread_rate_limit_per_user?integerDefault duration in seconds a user has to wait before sending another message in newly created threads; this field is copied to the thread at creation time and does not live update
permissions? 5stringComputed permissions for the invoking user in the channel, including overwrites
flags?integerThe channel's flags
available_tags?array[tag object]The tags that can be used in a thread-only channel (max 20)
applied_tags?array[snowflake]The IDs of tags that are applied to a thread in a thread-only channel (max 5)
default_reaction_emoji??default reaction objectThe emoji to show in the add reaction button on a thread in a thread-only channel
default_forum_layout?integerThe default layout of a thread-only channel
default_sort_order??integerThe default sort order of a thread-only channel's threads (default LATEST_ACTIVITY)
icon_emoji??icon emoji objectThe emoji to show next to the channel name in channels list
is_message_request?booleanWhether the DM is a message request
is_message_request_timestamp??ISO8601 timestampWhen the message request was created
is_spam?booleanWhether the DM is a spam message request
theme_color??integerThe background color of the channel icon emoji encoded as an integer representation of hexadecimal color code
status? 6?stringThe status of the voice channel (max 500 characters)
hd_streaming_until??ISO8601 timestampWhen the HD streaming entitlement expires for the voice channel
hd_streaming_buyer_id??snowflakeThe ID of the user who applied the HD streaming entitlement to the voice channel
blocked_user_warning_dismissed? 7booleanWhether the user has acknowledged the presence of blocked users in the group DM

1 The maximum user limit for stage channels is always 10000 and cannot be set to 0.

2 rate_limit_per_user also applies to thread creation. Users can send one message and create one thread during each rate_limit_per_user interval.

3 Only included in Gateway events.

4 This field is not automatically copied into new threads created in the channel. It should be manually set when creating a thread.

5 Only returned when part of the resolved data received in a slash command interaction or when permissions is set to true when fetching Get Guild Channels.

6 Only included in the Gateway Guild object.

7 Only included in Gateway events and when fetched from the Get Private Channels endpoint.

Channel Type
TypeNameDescription
0GUILD_TEXTA text channel within a guild
1DMA private channel between two users
2GUILD_VOICEA voice channel within a guild
3GROUP_DMA private channel between multiple users
4GUILD_CATEGORYAn organizational category that contains up to 50 channels
5GUILD_NEWSAlmost identical to GUILD_TEXT, a channel that users can follow and crosspost into their own guild
6GUILD_STOREA channel in which game developers can sell their game on Discord
7GUILD_LFGA channel where users can match up for various games
8LFG_GROUP_DMA private channel between multiple users for a group within an LFG channel
9THREAD_ALPHAThe first iteration of the threads feature, never widely used
10NEWS_THREADA temporary sub-channel within a GUILD_NEWS channel
11PUBLIC_THREADa temporary sub-channel within a GUILD_TEXT, GUILD_FORUM, or GUILD_MEDIA channel
12PRIVATE_THREADa temporary sub-channel within a GUILD_TEXT channel that is only viewable by those invited and those with the MANAGE_THREADS permission
13GUILD_STAGE_VOICEA voice channel for hosting events with an audience in a guild
14GUILD_DIRECTORYThe main channel in a hub containing the listed guilds
15GUILD_FORUMA channel that can only contain threads
16GUILD_MEDIAA channel that can only contain threads in a gallery view
17LOBBYA game lobby channel
18DM_SDKA private channel created by the social layer SDK
Channel Flags
ValueNameDescription
1 << 0GUILD_FEED_REMOVEDThis guild channel is hidden from the guild's feed
1 << 1PINNEDThis thread is pinned to the top of its parent thread-only channel
1 << 2ACTIVE_CHANNELS_REMOVEDThis guild channel has been removed from the guild's active channels
1 << 4REQUIRE_TAGThis thread-only channel requires a tag to create threads in
1 << 5SPAMThis channel is marked as spam
1 << 7GUILD_RESOURCE_CHANNELThis guild channel is used as a read-only resource for onboarding and is not shown in the channel list
1 << 8CLYDE_AIThis thread is created by Clyde AI, which has full access to all message content
1 << 9SCHEDULED_FOR_DELETIONThis guild channel is scheduled for deletion and is not shown in the UI
1 << 10MEDIA_CHANNEL 1This forum channel is a media channel
1 << 11SUMMARIES_DISABLEDThis guild channel has summaries disabled
1 << 12APPLICATION_SHELF_CONSENTThis private channel's recipients consented to the application shelf
1 << 13ROLE_SUBSCRIPTION_TEMPLATE_PREVIEW_CHANNELThis role subscription tier for this guild channel has not been published yet
1 << 14BROADCASTINGThis group DM is used for broadcasting a live stream
1 << 15HIDE_MEDIA_DOWNLOAD_OPTIONSThis media channel has the embedded download options hidden for media attachments
1 << 16JOIN_REQUEST_INTERVIEW_CHANNELThis group DM is used for guild join request interviews
1 << 17OBFUSCATED 2This channel is unavailable for the current user and has its details obfuscated

1 Media channels are now represented by the GUILD_MEDIA channel type.

2 The channel's name and topic are always returned as ___hidden___.

Recipient Flags
ValueNameDescription
1 << 0DISMISSED_IN_GAME_MESSAGE_NUXThe user has dismissed the IN_GAME_MESSAGE_NUX message for this DM channel
Video Quality Mode
ValueNameDescription
1AUTODiscord chooses the quality for optimal performance
2FULL720p quality
Forum Layout Type
ValueNameDescription
0DEFAULTNo layout type explicitly set
1LISTThreads are displayed in a list
2GRIDThreads are displayed in a collection of tiles
Sort Order Type
ValueNameDescription
0LATEST_ACTIVITYSort by the most recent message in the thread
1CREATION_TIMESort by when the thread was created (from most recent to oldest)
Example Guild Category Channel
{
"id": "399942396007890945",
"type": 4,
"name": "lounge",
"position": 0,
"flags": 0,
"parent_id": null,
"guild_id": "41771983423143937",
"permission_overwrites": []
}
Example Guild Text Channel
{
"id": "41771983423143937",
"guild_id": "41771983423143937",
"name": "general",
"type": 0,
"position": 6,
"flags": 0,
"permission_overwrites": [],
"rate_limit_per_user": 2,
"nsfw": true,
"topic": "24/7 chat about how to gank Mike #2",
"last_message_id": "155117677105512449",
"parent_id": "399942396007890945",
"last_pin_timestamp": "2023-02-17T09:22:28+00:00",
"default_auto_archive_duration": 10080,
"default_thread_rate_limit_per_user": 0
}
Example Guild News Channel

Users can post or publish messages in this type of channel if they have the proper permissions. These are called "Announcement Channels" in the client.

{
"id": "41771983423143937",
"guild_id": "41771983423143937",
"name": "important-news",
"type": 5,
"position": 6,
"flags": 0,
"permission_overwrites": [],
"nsfw": true,
"topic": "Rumors about Half Life 3",
"last_message_id": "155117677105512449",
"parent_id": "399942396007890945",
"last_pin_timestamp": "2023-02-17T09:22:28+00:00",
"default_auto_archive_duration": 10080,
"default_thread_rate_limit_per_user": 0
}
Example Guild Voice Channel
{
"id": "155101607195836416",
"last_message_id": "174629835082649376",
"type": 2,
"name": "ROCKET CHEESE",
"position": 5,
"flags": 0,
"parent_id": null,
"bitrate": 64000,
"user_limit": 0,
"rtc_region": null,
"guild_id": "41771983423143937",
"permission_overwrites": [],
"rate_limit_per_user": 0,
"nsfw": false
}
Example Guild Stage Channel
{
"id": "1053657210082836620",
"last_message_id": "1075473541174136834",
"type": 13,
"name": "EVENTS",
"position": 2,
"flags": 0,
"parent_id": null,
"topic": "",
"bitrate": 64000,
"user_limit": 10000,
"rtc_region": null,
"guild_id": "41771983423143937",
"permission_overwrites": [],
"rate_limit_per_user": 0,
"nsfw": false
}
Example Guild Forum Channel
{
"id": "1074357242700247173",
"last_message_id": "1075957063890509894",
"type": 15,
"name": "forum",
"position": 11,
"flags": 16,
"parent_id": "399942396007890945",
"topic": "",
"guild_id": "41771983423143937",
"permission_overwrites": [],
"rate_limit_per_user": 0,
"nsfw": false,
"available_tags": [
{
"id": "1076275719316983899",
"name": "Alien",
"emoji_id": null,
"emoji_name": "👽",
"moderated": true
}
],
"default_reaction_emoji": {
"emoji_id": "1066765913208139796",
"emoji_name": null
},
"default_auto_archive_duration": 10080,
"default_thread_rate_limit_per_user": 0,
"default_sort_order": null,
"default_forum_layout": 0
}
Example DM Channel
{
"last_message_id": "3343820033257021450",
"type": 1,
"id": "319674150115610528",
"flags": 0,
"is_message_request": false,
"is_message_request_timestamp": "2023-02-16T00:45:10.270751+00:00",
"is_spam": false,
"recipients": [
{
"id": "728342296696979526",
"username": "splatter",
"avatar": "40ab813a6e1b6170dc4e7d1f2331bfeb",
"discriminator": "0",
"public_flags": 4194304,
"banner": "a_999640fa66eb908d8ec2f969516b97c8",
"accent_color": 11983775,
"global_name": "not splatter",
"avatar_decoration_data": null,
"primary_guild": null
}
]
}
Example Group DM Channel
{
"name": "Some test channel",
"icon": null,
"recipients": [
{
"id": "728342296696979526",
"username": "splatter",
"avatar": "40ab813a6e1b6170dc4e7d1f2331bfeb",
"discriminator": "0",
"public_flags": 4194304,
"banner": "a_999640fa66eb908d8ec2f969516b97c8",
"accent_color": 11983775,
"global_name": "not splatter",
"avatar_decoration_data": null,
"primary_guild": null
},
{
"id": "211270674482724864",
"username": "11pixels",
"avatar": "40e250de9c74346c480e7e16da242b47",
"discriminator": "0",
"public_flags": 4194880,
"banner": "785814ab5375e10deafe9e7de256dd0e",
"accent_color": 47615,
"global_name": "12pixels",
"avatar_decoration_data": null,
"primary_guild": null
}
],
"last_message_id": "3343820033257021450",
"type": 3,
"id": "319674150115710528",
"flags": 0,
"owner_id": "82198810841029460",
"blocked_user_warning_dismissed": true
}
Example Thread Channel

Threads can be either archived or active. Archived threads are generally immutable. To send a message or add a reaction, a thread must first be unarchived. The API will helpfully automatically unarchive a thread when sending a message in that thread.

Unlike with channels, the API will only sync updates to users about threads the current user can view. When receiving a Guild Create payload, the API will only include active threads the current user can view. Threads inside of private channels are completely private to the members of that private channel. As such, when gaining access to a channel in a subscribed guild the API sends a Thread List Sync, which includes all active threads in that channel.

Threads also track membership. Users must be added to a thread before sending messages in them. The API will helpfully automatically add users to a thread when sending a message in that thread.

Guilds have limits on the number of active threads and members per thread. Once these are reached additional threads cannot be created or unarchived, and users cannot be added. Threads do not count against the per-guild channel limit.

The threads topic has some more information.

{
"id": "41771983423143937",
"guild_id": "41771983423143937",
"parent_id": "41771983423143937",
"owner_id": "41771983423143937",
"name": "don't buy dota-2",
"type": 11,
"last_message_id": "155117677105512449",
"message_count": 1,
"member_count": 5,
"rate_limit_per_user": 2,
"thread_metadata": {
"archived": false,
"auto_archive_duration": 1440,
"archive_timestamp": "2021-04-12T23:40:39.855793+00:00",
"locked": false
},
"total_message_sent": 1,
"applied_tags": []
}

Partial Channel Object

A channel referenced in an invite or message.

Partial Channel Structure
FieldTypeDescription
idsnowflakeThe ID of the channel
typeintegerThe type of channel
name?stringThe name of the channel (1-100 characters)
recipients? 1array[partial user object]The recipients of the DM; only the username field is present
icon??stringThe group DM's icon hash
guild_id? 2?snowflakeThe ID of the guild the channel is in

1 Only present when the channel is fetched from an invite with with_counts set to true.

2 Not present when the channel is fetched from an invite, as it can be inferred from the guild_id field.

Example Partial Channel Object
{
"id": "1065785999734607943",
"name": null,
"type": 3,
"icon": null,
"recipients": [
{
"username": "alien"
},
{
"username": "alien.2.electric.boogaloo"
}
]
}

Followed Channel Object

An object that represents a channel that has been followed by a webhook.

Followed Channel Structure
FieldTypeDescription
channel_idsnowflakeThe source channel ID
webhook_idsnowflakeCreated target webhook ID

Permission Overwrite Object

See permissions for more information about the allow and deny fields.

Permission Overwrite Structure
FieldTypeDescription
idsnowflakeRole or user ID
typeintegerThe type of overwritten entity
allow 1stringThe bitwise value of all allowed permissions
deny 1stringThe bitwise value of all disallowed permissions

1 When sending, these fields are optional and will default to 0.

Permission Overwrite Type
ValueNameDescription
0rolePermissions based on a role
1memberPermissions for a specific member

Thread Metadata Object

The thread metadata object contains a number of thread-specific channel fields that are not needed by other channel types.

Thread Metadata Structure
FieldTypeDescription
archivedbooleanWhether the thread is archived
auto_archive_durationintegerDuration in minutes to stop showing in the channel list after inactivity (one of 60, 1440, 4320, 10080)
archive_timestampISO8601 timestampTimestamp when the thread's archive status was last changed, used for calculating recent activity
lockedbooleanWhether the thread is locked; when a thread is locked, only users with MANAGE_THREADS can unarchive it
invitable?booleanWhether non-moderators can add other non-moderators to a thread; only available on private threads
create_timestamp??ISO8601 timestampTimestamp when the thread was created; only populated for threads created after 2022-01-09

Thread Member Object

A thread member object contains information about a user that has joined a thread.

Thread Member Structure
FieldTypeDescription
id? 1snowflakeThe ID of the thread
user_id? 1snowflakeThe ID of the user
join_timestampISO8601 timestampThe time the current user last joined the thread
flags 2integerThe user's thread flags
muted? 2booleanWhether the user has muted the thread
mute_config? 2?mute config objectThe mute metadata for the thread
member? 1 3guild member objectThe member object for the user

1 These fields are omitted on the member sent within each thread in the Guild Create event.

2 These fields are omitted for thread members other than the current user.

3 The member field is only present when with_member is set to true when fetching Get Thread Members or Get Thread Member.

Thread Member Flags
ValueNameDescription
1 << 0HAS_INTERACTEDThe user has interacted with the thread
1 << 1ALL_MESSAGESThe user receives notifications for all messages
1 << 2ONLY_MENTIONSThe user receives notifications only for messages that @mention them
1 << 3NO_MESSAGESThe user does not receive any notifications

Default Reaction Object

An object that specifies the emoji to use as the default way to react to a GUILD_FORUM or GUILD_MEDIA channel post.

Default Reaction Structure
FieldTypeDescription
emoji_id 1?snowflakeThe ID of a guild's custom emoji
emoji_name 1?stringThe unicode character of the emoji

1 At most one of emoji_id and emoji_name may be set to a non-null value.

Icon Emoji Object

An object that specifies the emoji to use as the icon displayed next to a channel's name.

Icon Emoji Structure
FieldTypeDescription
id 1?snowflakeThe ID of a guild's custom emoji
name 1?stringThe unicode character of the emoji

1 At most one of id and name may be set to a non-null value.

Forum Tag Object

An object that represents a tag that is able to be applied to a thread in a GUILD_FORUM or GUILD_MEDIA channel.

Forum Tag Structure
FieldTypeDescription
idsnowflakeThe ID of the tag
namestringThe name of the tag (max 20 characters)
moderatedbooleanWhether this tag can only be added to or removed from threads by members with the MANAGE_THREADS permission
emoji_id 1?snowflakeThe ID of a guild's custom emoji
emoji_name 1?stringThe unicode character of the emoji

1 At most one of emoji_id and emoji_name may be set to a non-null value.

Mute Config Object

Represents the duration of a thread mute.

Mute Config Structure
FieldTypeDescription
end_time??ISO8601 timestampTimestamp representing when the mute ends
selected_time_windowintegerDuration of the mute in seconds, or -1 for indefinite

Endpoints

Get Private Channels

GET/users/@me/channels

Returns a list of active private channel objects the user is participating in.

Get DM Channel

GET/users/@me/dms/{user.id}

Returns an existing DM channel object with a user.

Create Private Channel

POST/users/@me/channels

One recipient creates or returns an existing DM channel, none or multiple recipients create a group DM channel. Returns a private channel object. Fires a Channel Create Gateway event.

If multiple channels with a single recipient exist, the most recent channel is returned.

JSON Params
FieldTypeDescription
recipient_id? (deprecated)snowflakeThe recipient to DM
recipients?array[snowflake]The users to include in the private channel
access_tokens? 1array[string]The access tokens of users that have granted your app the gdm.join scope
nicks? 1objectA mapping of user IDs to their respective nicknames

1 Only usable for OAuth2 requests (which can only create group DMs).

Get Guild Channels

GET/guilds/{guild.id}/channels

Returns a list of guild channel objects for the guild. Does not include threads.

Query String Params
FieldTypeDescription
permissions?booleanWhether to return calculated permissions for the invoking user in each channel (default false)

Get Guild Top Read Channels

GET/guilds/{guild.id}/top-read-channels

Returns a list of snowflakes representing up to 10 of the top read channels in the guild.

Create Guild Channel

POST/guilds/{guild.id}/channels

Creates a new channel in the guild. Requires the MANAGE_CHANNELS permission. If setting permission overwrites, only permissions you have in the guild can be allowed/denied. Setting MANAGE_ROLES permission in channels is only possible for guild administrators. Returns the new channel object on success. Fires a Channel Create Gateway event.

JSON Params
FieldTypeDescriptionChannel Type
namestringThe name of the channel (1-100 characters)All
position??integerSorting position of the channelAll
type??integerThe type of channelAll
topic??stringThe channel topic (max 1024 characters)Text, News, Stage, Forum, Media
nsfw??booleanWhether the channel is NSFWText, News, Voice, Stage, Forum, Media
rate_limit_per_user??integerDuration in seconds a user has to wait before sending another message (max 21600); bots, as well as users with the permission MANAGE_MESSAGES or MANAGE_CHANNELS, are unaffectedText, News, Voice, Stage, Forum, Media
bitrate? 1?integerThe bitrate (in bits) of the voice channelVoice, Stage
user_limit? 2?integerThe user limit of the voice channel (max 99, 0 refers to no limit)Voice, Stage
permission_overwrites??array[permission overwrite object]Explicit permission overwrites for members and rolesAll
parent_id??snowflakeThe ID of the parent category for the guild channelText, News, Voice, Stage, Forum, Media
rtc_region??stringThe voice region ID for the voice channel (automatic when null)Voice, Stage
video_quality_mode??integerThe camera video quality mode of the voice channelVoice, Stage
default_auto_archive_duration??integerDefault duration in minutes for newly created threads to stop showing in the channel list after inactivity (one of 60, 1440, 4320, 10080)Text, News, Forum, Media
default_thread_rate_limit_per_user??integerDefault duration in seconds a user has to wait before sending another message in newly created threads; this field is copied to the thread at creation time and does not live updateText, News, Forum, Media
available_tags? 3?array[partial tag object]The tags that can be used in a thread-only channel (max 20)Forum, Media
default_reaction_emoji??default reaction objectThe emoji to show in the add reaction button on a thread in a thread-only channelForum, Media
default_forum_layout??integerThe default layout of a forum channelForum
default_sort_order??integerThe default sort order of a thread-only channel's threadsForum, Media

1 For voice channels, guilds without premium (boost level) can set bitrate up to 96000, guilds with premium tier 1 can set up to 128000, guilds with premium tier 2 can set up to 256000, and guilds with premium tier 3 or the VIP_REGIONS guild feature can set up to 384000. For stage channels, bitrate can only be set up to 64000.

2 The maximum user limit for stage channels is always 10000 and cannot be set to 0.

3 Only the name field is required.

Modify Guild Channel Positions

PATCH/guilds/{guild.id}/channels

Modifies the positions of a set of channel objects for the guild. Requires the MANAGE_CHANNELS permission. Returns a 204 empty response on success. Fires multiple Channel Update Gateway events.

This endpoint takes a JSON array of parameters in the following format:

JSON Params
FieldTypeDescription
idsnowflakeThe ID of the channel
position??integerSorting position of the channel
lock_permissions??booleanSyncs the permission overwrites with the new parent, if moving to a new category
parent_id??snowflakeThe ID of the parent category for the channel

Get Channel

GET/channels/{channel.id}

Returns a channel object for a given channel ID. If the channel is a thread, a thread member object is included in the returned result.

Modify Channel

PATCH/channels/{channel.id}

Updates a channel's settings. Returns a channel on success. Fires a Channel Update or Thread Update Gateway event.

JSON Params

If modifying a guild channel, requires the MANAGE_CHANNELS permission for the guild. If modifying permission overwrites, the MANAGE_ROLES permission is required. Only permissions you have in the guild or parent channel (if applicable) can be allowed/denied (unless you have a MANAGE_ROLES overwrite in the channel). Fires a Channel Update Gateway event. If modifying a category, individual Channel Update events will fire for each child channel that also changes.

If modifying a thread and setting archived to false, when locked is also false, only the SEND_MESSAGES permission is required. Otherwise, requires the MANAGE_THREADS permission. Requires the thread to have archived set to false or be set to false in the request. Fires a Thread Update Gateway event.

FieldTypeDescriptionChannel Type
name?stringThe name of the channel (1-100 characters)Text, News, Voice, Category, Stage, Forum, Media, Thread, Group DM
type?integerThe type of channel; only conversion between text and news is supported and only in guilds with the "NEWS" featureText, News
position??integerSorting position of the channelText, News, Voice, Category, Stage, Forum, Media
topic??stringThe channel topic (max 1024 characters)Text, News, Stage, Forum, Media
icon?image dataThe group DM's iconGroup DM
nsfw??booleanWhether the channel is NSFWText, News, Voice, Stage, Forum
rate_limit_per_user??integerDuration in seconds a user has to wait before sending another message (max 21600); bots, as well as users with the permission MANAGE_MESSAGES or MANAGE_CHANNELS, are unaffectedText, News, Voice, Stage, Forum, Media, Thread
bitrate? 1?integerThe bitrate (in bits) of the voice channelVoice, Stage
user_limit? 2?integerthe user limit of the voice channel (max 99, 0 refers to no limit)Voice, Stage
permission_overwrites??array[permission overwrite object]Explicit permission overwrites for members and rolesText, News, Voice, Category, Stage, Forum, Media
parent_id??snowflakeThe ID of the parent category for the guild channelText, News, Voice, Stage, Forum, Media
owner??snowflakeThe ID of the owner for the group DMGroup DM
rtc_region??stringThe voice region ID for the voice channel (automatic when null)Voice, Stage
video_quality_mode??integerThe camera video quality mode of the voice channelVoice, Stage
default_auto_archive_duration??integerDefault duration in minutes for newly created threads to stop showing in the channel list after inactivity (one of 60, 1440, 4320, 10080)Text, News, Forum, Media
default_thread_rate_limit_per_user?integerDefault duration in seconds a user has to wait before sending another message in newly created threads; this field is copied to the thread at creation time and does not live updateText, News, Forum, Media
auto_archive_duration?integerDuration in minutes to automatically archive the thread after recent activity (one of 60, 1440, 4320, 10080)Thread
archived??booleanWhether the thread is archivedThread
locked??booleanWhether the thread is locked; when a thread is locked, only users with MANAGE_THREADS can unarchive itThread
invitable??booleanWhether non-moderators can add other non-moderators to a threadPrivate Thread
flags?integerThe channel's flags (only GUILD_FEED_REMOVED, PINNED, ACTIVE_CHANNELS_REMOVED, and REQUIRE_TAG can be set)All
available_tags? 2array[partial tag object]The tags that can be used in a thread-only channel (max 20)Forum, Media
applied_tags?array[snowflake]The IDs of tags that are applied to a thread in a thread-only channel (max 5)Thread
default_reaction_emoji??default reaction objectThe emoji to show in the add reaction button on a thread in a thread-only channelForum, Media
default_forum_layout?integerThe default layout of a forum channelForum
default_sort_order??integerThe default sort order of a thread-only channel's threadsForum, Media
icon_emoji??icon emoji objectThe emoji to show next to the channel name in channels listText, News, Voice, Stage, Forum
theme_color??integerThe background color of the channel icon emoji encoded as an integer representation of hexadecimal color codeText, News, Voice, Stage, Forum

1 For voice channels, guilds without premium (boost level) can set bitrate up to 96000, guilds with premium tier 1 can set up to 128000, guilds with premium tier 2 can set up to 256000, and guilds with premium tier 3 or the VIP_REGIONS guild feature can set up to 384000. For stage channels, bitrate can only be set up to 64000.

2 The maximum user limit for stage channels is always 10000 and cannot be set to 0.

3 Only the name field is required (id may be passed to denote an existing tag).

Delete Channel

DELETE/channels/{channel.id}

Deletes a channel, or closes a private message. Requires the MANAGE_CHANNELS permission for the guild, or MANAGE_THREADS if the channel is a thread. Deleting a category does not delete its child channels; they will have their parent_id removed and a Channel Update Gateway event will fire for each of them. Returns a channel object on success. Fires a Channel Delete or Thread Delete Gateway event.

Query String Params
FieldTypeDescription
silent?booleanWhether to leave the group DM without sending a system message (default false)

Delete Read State

DELETE/channels/{channel.id}/messages/ack

Deletes a channel's read state for the current user. Returns a 204 empty response on success.

This should be used to delete various read states of channels the client has not been able to access for a while.

JSON Params
FieldTypeDescription
version?integerThe version of the read state feature you are using (default 1, should be 2 to allow the usage of read state types other than CHANNEL)
read_state_type?integerThe read state type to delete (default CHANNEL)

Modify Channel Status

PUT/channels/{channel.id}/voice-status

Sets a voice channel's status. Requires the SET_VOICE_CHANNEL_STATUS permission and additionally the MANAGE_CHANNELS permission if the current user is not connected to the voice channel. Returns a 204 empty response on success. Fires a Voice Channel Status Update Gateway event.

JSON Params
FieldTypeDescription
status?stringThe status of the voice channel (max 500 characters)

Modify Channel Permissions

PUT/channels/{channel.id}/permissions/{overwrite.id}

Edits the channel permission overwrites for a user or role in a channel. Only usable for guild channels. Requires the MANAGE_ROLES permission. Only permissions you have in the guild or parent channel (if applicable) can be allowed/denied (unless you have a MANAGE_ROLES overwrite in the channel). Returns a 204 empty response on success. Fires a Channel Update Gateway event. For more information about permissions, see permissions.

JSON Params
FieldTypeDescription
typeintegerEither 0 (role) or 1 (member)
allow?stringThe bitwise value of all allowed permissions
deny?stringThe bitwise value of all disallowed permissions

Delete Channel Permission

DELETE/channels/{channel.id}/permissions/{overwrite.id}

Deletes a channel permission overwrite for a user or role in a channel. Only usable for guild channels. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success. Fires a Channel Update Gateway event. For more information about permissions, see permissions

Follow Channel

POST/channels/{channel.id}/followers

Follows a News Channel to send messages to a target channel. Requires the MANAGE_WEBHOOKS permission in the target channel. Returns a followed channel object on success. Fires a Webhooks Update Gateway event for the target channel.

JSON Params
FieldTypeDescription
webhook_channel_idsnowflakeThe ID of the target channel

Trigger Typing Indicator

POST/channels/{channel.id}/typing

Posts a typing indicator for the specified channel. Returns a 204 empty response on success. Fires a Typing Start Gateway event.

Get Call Eligibility

GET/channels/{channel.id}/call

Checks if the current user is eligible to start a call in the DM channel.

Response Body
FieldTypeDescription
ringablebooleanWhether the user is additionally eligible to ring the other recipient(s)

Modify Call

PATCH/channels/{channel.id}/call

Modifies the active call in the private channel. Returns a 204 empty response on success. Fires a Call Update Gateway event.

JSON Params
FieldTypeDescription
region?stringThe voice region ID for the call

Ring Channel Recipients

POST/channels/{channel.id}/call/ring

Rings the recipients of a private channel to notify them of an active call. Returns a 204 empty response on success. Fires a Call Update Gateway event.

JSON Params
FieldTypeDescription
recipients??array[snowflake]The recipients to ring (default all)

Stop Ringing Channel Recipients

POST/channels/{channel.id}/call/stop-ringing

Stops ringing the recipients of a private channel about an active call. Returns a 204 empty response on success. Fires a Call Update Gateway event.

JSON Params
FieldTypeDescription
recipients??array[snowflake]The recipients to stop ringing

Add Channel Recipient

PUT/channels/{channel.id}/recipients/{user.id}

Adds a recipient to a group DM. Returns a 204 empty response on success. Fires a Channel Recipient Add Gateway event.

JSON Params
FieldTypeDescription
access_token? 1stringAccess token of a user that has granted your app the gdm.join scope
nick?stringNickname of the user being added

1 Only required for OAuth2 requests.

Remove Channel Recipient

DELETE/channels/{channel.id}/recipients/{user.id}

Removes a recipient from a group DM. Requires ownership of the target channel. Returns a 204 empty response on success. Fires a Channel Recipient Remove Gateway event.

Update Message Request

PUT/channels/{channel.id}/recipients/@me

Modifies a message request's status. Returns a DM channel object on success. Fires a Channel Update Gateway event.

JSON Params
FieldTypeDescription
consent_statusintegerThe new consent status
ValueNameDescription
0UNSPECIFIEDThe DM isn't a message request
1PENDINGThe message request is pending
2ACCEPTEDThe message request was accepted
3REJECTEDThe message request was rejected

Reject Message Request

DELETE/channels/{channel.id}/recipients/@me

Rejects and deletes a pending message request. Returns a DM channel object on success. Fires Channel Update, Message ACK, Channel Delete, and optionally DM Settings Upsell Show Gateway events.

Batch Reject Message Requests

PUT/channels/recipients/@me/batch-reject

Rejects and deletes multiple pending message requests. Returns a list of DM channel objects on success. Fires multiple Channel Update, Message ACK, Channel Delete, and optionally DM Settings Upsell Show Gateway events.

JSON Params
FieldTypeDescription
channel_idsarray[snowflake]The IDs of the message requests to reject (max 100)

Get Supplemental Message Request Data

GET/users/@me/message-requests/supplemental-data

Returns a list of supplemental message request objects with the message that triggered each message request.

Query String Params
FieldTypeDescription
channel_idsarray[snowflake]The IDs of the message requests to fetch (1-25)
Supplemental Message Request Structure
FieldTypeDescription
channel_idsnowflakeThe ID of the message request
message_previewmessage objectThe trigger message

Dismiss Blocked User Warning

POST/channels/{channel.id}/blocked-user-warning-dismissal

Acknowledges that a group DM contains users the current user has blocked. Returns a 200 empty response on success. Fires a Channel Update Gateway event.

Get Guild Active Threads

GET/guilds/{guild.id}/threads/active

Returns all active threads in the guild, including public and private threads. Threads are ordered by their id, in descending order.

Response Body
FieldTypeDescription
threadsarray[channel object]The active threads
membersarray[thread members object]A thread member object for each returned thread the current user has joined

Get Active Threads

GET/channels/{channel.id}/threads/active

Returns all active threads in the channel, including public and private threads. Threads are ordered by their id, in descending order.

Response Body
FieldTypeDescription
threadsarray[channel object]The active threads
membersarray[thread member object]A thread member object for each returned thread the current user has joined
has_morebooleanWhether there are potentially additional threads that could be returned on a subsequent call

Get Public Archived Threads

GET/channels/{channel.id}/threads/archived/public

Returns archived threads in the channel that are public. When called on a GUILD_TEXT channel, returns threads of type PUBLIC_THREAD. When called on a GUILD_NEWS channel returns threads of type NEWS_THREAD. Threads are ordered by archive_timestamp, in descending order. Requires the READ_MESSAGE_HISTORY permission.

Query String Params
FieldTypeDescription
before?ISO8601 timestampGet threads before this timestamp
limit?integerMax number of threads to return (2-100, default 50)
Response Body
FieldTypeDescription
threadsarray[channel object]The public, archived threads
membersarray[thread member object]A thread member object for each returned thread the current user has joined
has_morebooleanWhether there are potentially additional threads that could be returned on a subsequent call

Get Private Archived Threads

GET/channels/{channel.id}/threads/archived/private

Returns archived threads in the channel that are of type PRIVATE_THREAD. Threads are ordered by archive_timestamp, in descending order. Requires both the READ_MESSAGE_HISTORY and MANAGE_THREADS permissions.

Query String Params
FieldTypeDescription
before?ISO8601 timestampGet threads before this timestamp
limit?integerMax number of threads to return (2-100, default 50)
Response Body
FieldTypeDescription
threadsarray[channel object]The private, archived threads
membersarray[thread member object]A thread member object for each returned thread the current user has joined
has_morebooleanWhether there are potentially additional threads that could be returned on a subsequent call

Get Joined Private Archived Threads

GET/channels/{channel.id}/users/@me/threads/archived/private

Returns archived threads in the channel that are of type PRIVATE_THREAD, and the user has joined. Threads are ordered by their id, in descending order. Requires the READ_MESSAGE_HISTORY permission.

Query String Params
FieldTypeDescription
before?snowflakeGet threads before this channel ID
limit?integerMax number of threads to return (2-100, default 50)
Response Body
FieldTypeDescription
threadsarray[channel object]The private, archived threads the current user has joined
membersarray[thread member object]A thread member object for each returned thread the current user has joined
has_morebooleanWhether there are potentially additional threads that could be returned on a subsequent call

Search Threads

GET/channels/{channel.id}/threads/search

Returns threads in the channel that match the search parameters. Requires the READ_MESSAGE_HISTORY permission.

Query String Params
FieldTypeDescription
name?stringSearch query to look for matching threads (2-100 characters)
tag?array[snowflake]The tag IDs to filter results by
tag_setting?stringHow to restrict the returned threads by tag (match_some or match_all, default match_some)
archived?booleanWhether to restrict the search to only active or archived threads (default both)
sort_by?stringThe sorting algorithm to use
sort_order?stringThe direction to sort (asc or desc, default desc)
limit?integerMax number of threads to return (1-25, default 25)
offset?integerNumber of threads to skip before returning results
Thread Sort Type
ValueDescription
last_message_timeSort by the last message sent in the thread (default)
archive_timeSort by when the thread was last archived
relevanceSort by relevance to the current user
creation_timeSort by when the thread was created
Response Body
FieldTypeDescription
threadsarray[channel object]The threads that match the search parameters
membersarray[thread member object]A thread member object for each returned thread the current user has joined
has_morebooleanWhether there are potentially additional threads that could be returned on a subsequent call
total_resultsintegerThe total number of threads that match the search parameters
first_messagesarray[message object]The first messages of each thread

Create Thread from Message

POST/channels/{channel.id}/messages/{message.id}/threads

Creates a new thread from an existing message. Returns a channel on success. Fires a Thread Create and a Message Update Gateway event.

When called on a GUILD_TEXT channel, creates a PUBLIC_THREAD. When called on a GUILD_NEWS channel, creates a NEWS_THREAD.

JSON Params
FieldTypeDescription
namestringThe name of the channel (1-100 characters)
auto_archive_duration?integerDuration in minutes to stop showing in the channel list after inactivity (one of 60, 1440, 4320, 10080, default 4320)
rate_limit_per_user?integerDuration in seconds a user has to wait before sending another message (max 21600); bots, as well as users with the permission MANAGE_MESSAGES or MANAGE_CHANNELS, are unaffected

Create Thread

POST/channels/{channel.id}/threads

Creates a new thread that is not connected to an existing message. Returns a channel (with an optional extra message key containing the starter message) on success. Fires a Thread Create Gateway event.

In thread-only channels:

  • The type of the created thread is PUBLIC_THREAD.
  • See message formatting for more information on how to properly format messages.
  • The current user must have the SEND_MESSAGES permission (CREATE_PUBLIC_THREADS is ignored).
  • The maximum request size when sending a message is 100 MiB.
  • For the embed object, you can set every field except type (it will be rich regardless of if you try to set it), provider, video, and any height, width, or proxy_url values for images.
JSON Params
FieldTypeDescription
namestringThe name of the channel (1-100 characters)
auto_archive_duration?integerDuration in minutes to stop showing in the channel list after inactivity (one of 60, 1440, 4320, 10080, default 4320)
rate_limit_per_user?integerDuration in seconds a user has to wait before sending another message (max 21600); bots, as well as users with the permission MANAGE_MESSAGES or MANAGE_CHANNELS, are unaffected
type? 1integerthe type of thread to create (default PRIVATE_THREAD)
invitable?booleanWhether non-moderators can add other non-moderators to a thread; only available when creating a private thread
applied_tags?array[snowflake]The IDs of the tags that are applied to a thread in a thread-only channel (max 5)
message? 1thread-only channel message params objectContents of the first message in the thread

1 In API v10, this will be changed to be a required field, with no default.

2 Required (and only available) when creating a thread in a thread-only channel.

Thread-Only Channel Message Params Structure
FieldTypeDescription
content?stringThe message contents (max 2000 characters)
embeds? 2array[embed object]Embedded rich content (max 6000 characters, max 10)
embed? 2 (deprecated)embed objectEmbedded rich content (max 6000 characters), deprecated in favor of embeds
allowed_mentions?allowed mention objectAllowed mentions for the message
components? 2array[message component object]Components to include with the message
sticker_ids?array[snowflake]IDs of up to 3 stickers to send in the message
activity?message activity objectThe rich presence activity to invite users to
application_id?snowflakeThe application ID of the activity to create a rich presence invite for (defaults to the primary activity if unspecified)
flags?integerThe message's flags (only SUPPRESS_EMBEDS, SUPPRESS_NOTIFICATIONS, and VOICE_MESSAGE can be set)
files[n]? 1file contentsContents of the file being sent (max 10)
payload_json? 1stringJSON-encoded body of non-file params
attachments? 1array[partial attachment object]Partial attachment objects with filename and description (max 10)

1 See Uploading Files for details.

2 Cannot be used by user accounts.

Get Channel Post Data

POST/channels/{channel.id}/post-data

Returns a mapping of thread IDs to their post data in a thread-only channel. Requires the READ_MESSAGE_HISTORY permission.

JSON Params
FieldTypeDescription
thread_idsarray[snowflake]The IDs of the threads to get post data for
Response Body
FieldTypeDescription
threadsobjectA mapping of thread IDs to their post data
Thread Post Data Structure
FieldTypeDescription
owner?guild member objectThe owner of the thread
first_message?message objectThe first message in the thread
Example Response
{
"threads": {
"1075957063890509894": {
"first_message": null,
"owner": null
}
}
}

Get Thread Members

GET/channels/{channel.id}/thread-members

Returns an array of thread members objects that are members of the thread.

Query String Params
FieldTypeDescription
with_member?booleanWhether to include a guild member object for each thread member
after?snowflakeGet thread members after this user ID
limit?integerMax number of thread members to return (1-100, default 100)

When with_member is set to true, the results will be paginated and each thread member object will include a member field containing a guild member object. Else, pagination is not available.

Get Thread Member

GET/channels/{channel.id}/thread-members/{user.id}

Returns a thread member object for the specified user if they are a member of the thread.

Query String Params
FieldTypeDescription
with_member?booleanWhether to include a guild member object for the thread member

Join Thread

PUT/channels/{channel.id}/thread-members/@me

Adds the current user to a thread. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a Thread Members Update and a Thread Create Gateway event.

Add Thread Member

PUT/channels/{channel.id}/thread-members/{user.id}

Adds another member to a thread. Requires the ability to send messages in the thread. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a Thread Members Update Gateway event.

Modify Thread Settings

PATCH/channels/{channel.id}/thread-members/@me/settings

Updates the current user's thread settings. Returns a thread member on success, or a 204 empty response when nothing changed. Fires a Thread Member Update Gateway event.

JSON Params
FieldTypeDescription
flags?integerThe user's thread flags flags (all except the first can be set)
muted?booleanWhether the user has muted the thread
mute_config??mute config objectThe mute metadata for the thread

Leave Thread

DELETE/channels/{channel.id}/thread-members/@me

Removes the current user from a thread. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a Thread Members Update Gateway event.

Remove Thread Member

DELETE/channels/{channel.id}/thread-members/{user.id}

Removes a member from a thread. Requires the MANAGE_THREADS permission, or the creator of the thread if it is a PRIVATE_THREAD. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a Thread Members Update Gateway event.

Create Channel Tag

POST/channels/{channel.id}/tags

Creates a new tag in the thread-only channel. Requires the MANAGE_CHANNELS permission. Returns a channel object on success. Fires a Channel Update Gateway event.

JSON Params
FieldTypeDescription
namestringThe name of the tag (max 20 characters)
moderated?booleanWhether this tag can only be added to or removed from threads by members with the MANAGE_THREADS permission (default false)
emoji_id? 1?snowflakeThe ID of a guild's custom emoji
emoji_name? 1?stringThe unicode character of the emoji

1 At most one of emoji_id and emoji_name may be set to a non-null value.

Modify Channel Tag

PUT/channels/{channel.id}/tags/{tag.id}

Replaces a tag in the thread-only channel. Requires the MANAGE_CHANNELS permission. Returns a channel object on success. Fires a Channel Update Gateway event.

JSON Params
FieldTypeDescription
namestringThe name of the tag (max 20 characters)
moderated?booleanWhether this tag can only be added to or removed from threads by members with the MANAGE_THREADS permission (default false)
emoji_id? 1?snowflakeThe ID of a guild's custom emoji
emoji_name? 1?stringThe unicode character of the emoji

1 At most one of emoji_id and emoji_name may be set to a non-null value.

Delete Channel Tag

DELETE/channels/{channel.id}/tags/{tag.id}

Deletes a tag in the thread-only channel. Requires the MANAGE_CHANNELS permission. Returns a channel object on success. Fires a Channel Update Gateway event.