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
Field | Type | Description |
---|---|---|
id | snowflake | The ID of the channel |
type | integer | The type of channel |
guild_id? | snowflake | The ID of the guild the channel is in |
position? | integer | Sorting position of the channel |
permission_overwrites? | array[permission overwrite object] | Explicit permission overwrites for members and roles |
name? | ?string | The name of the channel (1-100 characters) |
topic? | ?string | The channel topic (max 4096 characters for thread-only channels, max 1024 characters otherwise) |
nsfw? | boolean | Whether the channel is NSFW |
last_message_id? | ?snowflake | The 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? | integer | The bitrate (in bits) of the voice channel |
user_limit? 1 | integer | The user limit of the voice channel (max 99, 0 refers to no limit) |
rate_limit_per_user? 2 | integer | Duration 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 |
icon? | ?string | The group DM's icon hash |
managed? | boolean | Whether the group DM is managed by an application |
application_id? | snowflake | The ID of the application that manages the group DM |
owner_id? | snowflake | The ID of the owner of the group DM or thread |
owner? | ?guild member object | The owner of this thread; only included on certain API endpoints |
parent_id? | ?snowflake | The ID of the parent category/channel for the guild channel/thread |
last_pin_timestamp? | ?ISO8601 timestamp | When the last pinned message was pinned, if any |
rtc_region? | ?string | The voice region ID for the voice channel (automatic when null ) |
video_quality_mode? | integer | The camera video quality mode of the voice channel (default AUTO ) |
total_message_sent? | integer | The 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? | integer | The 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? | integer | An 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 object | Thread-specific channel metadata |
member? | thread member object | Thread member object for the current user, if they have joined the thread; only included on certain API endpoints |
default_auto_archive_duration? 3 | ?integer | Default 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? | integer | Default 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? 4 | string | Computed permissions for the invoking user in the channel, including overwrites |
flags? | integer | The 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 object | The emoji to show in the add reaction button on a thread in a thread-only channel |
default_forum_layout? | integer | The default layout of a thread-only channel |
default_sort_order? | ?integer | The default sort order of a thread-only channel's threads (default LATEST_ACTIVITY ) |
icon_emoji? | ?icon emoji object | The emoji to show next to the channel name in channels list |
is_message_request? | boolean | Whether the DM is a message request |
is_message_request_timestamp? | ?ISO8601 timestamp | When the message request was created |
is_spam? | boolean | Whether the DM is a spam message request |
theme_color? | ?integer | The background color of the channel icon emoji encoded as an integer representation of hexadecimal color code |
status? 5 | ?string | The status of the voice channel (max 500 characters) |
hd_streaming_until? | ?ISO8601 timestamp | When the HD streaming entitlement expires for the voice channel |
hd_streaming_buyer_id? | ?snowflake | The ID of the user who applied the HD streaming entitlement to the voice channel |
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 This field is not automatically copied into new threads created in the channel. It should be manually set when creating a thread.
4 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.
5 Only included in the Gateway Guild object.
Channel Type
Type | Name | Description |
---|---|---|
0 | GUILD_TEXT | A text channel within a guild |
1 | DM | A private channel between two users |
2 | GUILD_VOICE | A voice channel within a guild |
3 | GROUP_DM | A private channel between multiple users |
4 | GUILD_CATEGORY | An organizational category that contains up to 50 channels |
5 | GUILD_NEWS | Almost identical to GUILD_TEXT , a channel that users can follow and crosspost into their own guild |
6 | GUILD_STORE | A channel in which game developers can sell their game on Discord |
10 | NEWS_THREAD | A temporary sub-channel within a GUILD_NEWS channel |
11 | PUBLIC_THREAD | a temporary sub-channel within a GUILD_TEXT , GUILD_FORUM , or GUILD_MEDIA channel |
12 | PRIVATE_THREAD | a temporary sub-channel within a GUILD_TEXT channel that is only viewable by those invited and those with the MANAGE_THREADS permission |
13 | GUILD_STAGE_VOICE | A voice channel for hosting events with an audience in a guild |
14 | GUILD_DIRECTORY | The main channel in a hub containing the listed guilds |
15 | GUILD_FORUM | A channel that can only contain threads |
16 | GUILD_MEDIA | A channel that can only contain threads in a gallery view |
17 | LOBBY | A game lobby channel |
18 | DM_SDK | A private channel created by the social layer SDK |
Channel Flags
Value | Name | Description |
---|---|---|
1 << 0 | GUILD_FEED_REMOVED | This guild channel is hidden from the guild's feed |
1 << 1 | PINNED | This thread is pinned to the top of its parent thread-only channel |
1 << 2 | ACTIVE_CHANNELS_REMOVED | This guild channel has been removed from the guild's active channels |
1 << 4 | REQUIRE_TAG | This thread-only channel requires a tag to create threads in |
1 << 5 | SPAM | This channel is marked as spam |
1 << 7 | GUILD_RESOURCE_CHANNEL | This guild channel is used as a read-only resource for onboarding and is not shown in the channel list |
1 << 8 | CLYDE_AI | This thread is created by Clyde AI, which has full access to all message content |
1 << 9 | SCHEDULED_FOR_DELETION | This guild channel is scheduled for deletion and is not shown in the UI |
1 << 11 | SUMMARIES_DISABLED | This guild channel has summaries disabled |
1 << 13 | ROLE_SUBSCRIPTION_TEMPLATE_PREVIEW_CHANNEL | This role subscription tier for this guild channel has not been published yet |
1 << 14 | BROADCASTING | This group DM is used for broadcasting a live stream |
1 << 15 | HIDE_MEDIA_DOWNLOAD_OPTIONS | This media channel has the embedded download options hidden for media attachments |
1 << 16 | JOIN_REQUEST_INTERVIEW_CHANNEL | This group DM is used for guild join request interviews |
1 Media channels are now represented by the GUILD_MEDIA
channel type.
Video Quality Mode
Value | Name | Description |
---|---|---|
1 | AUTO | Discord chooses the quality for optimal performance |
2 | FULL | 720p quality |
Forum Layout Type
Value | Name | Description |
---|---|---|
0 | DEFAULT | No layout type explicitly set |
1 | LIST | Threads are displayed in a list |
2 | GRID | Threads are displayed in a collection of tiles |
Sort Order Type
Value | Name | Description |
---|---|---|
0 | LATEST_ACTIVITY | Sort by the most recent message in the thread |
1 | CREATION_TIME | Sort 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"}
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
Field | Type | Description |
---|---|---|
id | snowflake | The ID of the channel |
type | integer | The type of channel |
name | ?string | The name of the channel (1-100 characters) |
recipients? 1 | array[partial user object] | The recipients of the DM; only the username field is present |
icon? | ?string | The group DM's icon hash |
guild_id? 2 | ?snowflake | The 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
Field | Type | Description |
---|---|---|
channel_id | snowflake | The source channel ID |
webhook_id | snowflake | Created target webhook ID |
Permission Overwrite Object
See permissions for more information about the allow
and deny
fields.
Permission Overwrite Structure
Field | Type | Description |
---|---|---|
id | snowflake | Role or user ID |
type | integer | The type of overwritten entity |
allow 1 | string | The bitwise value of all allowed permissions |
deny 1 | string | The bitwise value of all disallowed permissions |
1 When sending, these fields are optional and will default to 0
.
Permission Overwrite Type
Value | Name | Description |
---|---|---|
0 | role | Permissions based on a role |
1 | member | Permissions 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
Field | Type | Description |
---|---|---|
archived | boolean | Whether the thread is archived |
auto_archive_duration | integer | Duration in minutes to stop showing in the channel list after inactivity (one of 60, 1440, 4320, 10080) |
archive_timestamp | ISO8601 timestamp | Timestamp when the thread's archive status was last changed, used for calculating recent activity |
locked | boolean | Whether the thread is locked; when a thread is locked, only users with MANAGE_THREADS can unarchive it |
invitable? | boolean | Whether non-moderators can add other non-moderators to a thread; only available on private threads |
create_timestamp? | ?ISO8601 timestamp | Timestamp 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
Field | Type | Description |
---|---|---|
id? 1 | snowflake | The ID of the thread |
user_id? 1 | snowflake | The ID of the user |
join_timestamp | ISO8601 timestamp | The time the current user last joined the thread |
flags 2 | integer | The user's thread flags |
muted? 2 | boolean | Whether the user has muted the thread |
mute_config? 2 | ?mute config object | The mute metadata for the thread |
member? 1 3 | guild member object | The 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
Value | Name | Description |
---|---|---|
1 << 0 | HAS_INTERACTED | The user has interacted with the thread |
1 << 1 | ALL_MESSAGES | The user receives notifications for all messages |
1 << 2 | ONLY_MENTIONS | The user receives notifications only for messages that @mention them |
1 << 3 | NO_MESSAGES | The 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
Field | Type | Description |
---|---|---|
emoji_id 1 | ?snowflake | The ID of a guild's custom emoji |
emoji_name 1 | ?string | The 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
Field | Type | Description |
---|---|---|
id 1 | ?snowflake | The ID of a guild's custom emoji |
name 1 | ?string | The 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
Field | Type | Description |
---|---|---|
id | snowflake | The ID of the tag |
name | string | The name of the tag (max 20 characters) |
moderated | boolean | Whether this tag can only be added to or removed from threads by members with the MANAGE_THREADS permission |
emoji_id 1 | ?snowflake | The ID of a guild's custom emoji |
emoji_name 1 | ?string | The 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
Field | Type | Description |
---|---|---|
end_time? | ?ISO8601 timestamp | Timestamp representing when the mute ends |
selected_time_window | integer | Duration 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
Field | Type | Description |
---|---|---|
recipient_id? (deprecated) | snowflake | The recipient to DM |
recipients? | array[snowflake] | The users to include in the private channel |
access_tokens? 1 | array[string] | The access tokens of users that have granted your app the gdm.join scope |
nicks? 1 | object | A 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
Field | Type | Description |
---|---|---|
permissions? | boolean | Whether 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
Field | Type | Description | Channel Type |
---|---|---|---|
name | string | The name of the channel (1-100 characters) | All |
position? | ?integer | Sorting position of the channel | All |
type? | ?integer | The type of channel | All |
topic? | ?string | The channel topic (max 1024 characters) | Text, News, Stage, Forum, Media |
nsfw? | ?boolean | Whether the channel is NSFW | Text, News, Voice, Stage, Forum, Media |
rate_limit_per_user? | ?integer | Duration 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 | Text, News, Voice, Stage, Forum, Media |
bitrate? 1 | ?integer | The bitrate (in bits) of the voice channel | Voice, Stage |
user_limit? 2 | ?integer | The 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 roles | All |
parent_id? | ?snowflake | The ID of the parent category for the guild channel | Text, News, Voice, Stage, Forum, Media |
rtc_region? | ?string | The voice region ID for the voice channel (automatic when null ) | Voice, Stage |
video_quality_mode? | ?integer | The camera video quality mode of the voice channel | Voice, Stage |
default_auto_archive_duration? | ?integer | Default 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? | ?integer | Default 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 | Text, 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 object | The emoji to show in the add reaction button on a thread in a thread-only channel | Forum, Media |
default_forum_layout? | ?integer | The default layout of a forum channel | Forum |
default_sort_order? | ?integer | The default sort order of a thread-only channel's threads | Forum, 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
Field | Type | Description |
---|---|---|
id | snowflake | The ID of the channel |
position? | ?integer | Sorting position of the channel |
lock_permissions? | ?boolean | Syncs the permission overwrites with the new parent, if moving to a new category |
parent_id? | ?snowflake | The 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.
Field | Type | Description | Channel Type |
---|---|---|---|
name? | string | The name of the channel (1-100 characters) | Text, News, Voice, Category, Stage, Forum, Media, Thread, Group DM |
type? | integer | The type of channel; only conversion between text and news is supported and only in guilds with the "NEWS" feature | Text, News |
position? | ?integer | Sorting position of the channel | Text, News, Voice, Category, Stage, Forum, Media |
topic? | ?string | The channel topic (max 1024 characters) | Text, News, Stage, Forum, Media |
icon? | image data | The group DM's icon | Group DM |
nsfw? | ?boolean | Whether the channel is NSFW | Text, News, Voice, Stage, Forum |
rate_limit_per_user? | ?integer | Duration 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 | Text, News, Voice, Stage, Forum, Media, Thread |
bitrate? 1 | ?integer | The bitrate (in bits) of the voice channel | Voice, Stage |
user_limit? 2 | ?integer | the 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 roles | Text, News, Voice, Category, Stage, Forum, Media |
parent_id? | ?snowflake | The ID of the parent category for the guild channel | Text, News, Voice, Stage, Forum, Media |
owner? | ?snowflake | The ID of the owner for the group DM | Group DM |
rtc_region? | ?string | The voice region ID for the voice channel (automatic when null ) | Voice, Stage |
video_quality_mode? | ?integer | The camera video quality mode of the voice channel | Voice, Stage |
default_auto_archive_duration? | ?integer | Default 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? | integer | Default 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 | Text, News, Forum, Media |
auto_archive_duration? | integer | Duration in minutes to automatically archive the thread after recent activity (one of 60, 1440, 4320, 10080) | Thread |
archived? | ?boolean | Whether the thread is archived | Thread |
locked? | ?boolean | Whether the thread is locked; when a thread is locked, only users with MANAGE_THREADS can unarchive it | Thread |
invitable? | ?boolean | Whether non-moderators can add other non-moderators to a thread | Private Thread |
flags? | integer | The channel's flags (only GUILD_FEED_REMOVED , PINNED , ACTIVE_CHANNELS_REMOVED , and REQUIRE_TAG can be set) | All |
available_tags? 2 | array[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 object | The emoji to show in the add reaction button on a thread in a thread-only channel | Forum, Media |
default_forum_layout? | integer | The default layout of a forum channel | Forum |
default_sort_order? | ?integer | The default sort order of a thread-only channel's threads | Forum, Media |
icon_emoji? | ?icon emoji object | The emoji to show next to the channel name in channels list | Text, News, Voice, Stage, Forum |
theme_color? | ?integer | The background color of the channel icon emoji encoded as an integer representation of hexadecimal color code | Text, 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
Field | Type | Description |
---|---|---|
silent? | boolean | Whether 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
Field | Type | Description |
---|---|---|
version? | integer | The 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? | integer | The 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
Field | Type | Description |
---|---|---|
status | ?string | The 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
Field | Type | Description |
---|---|---|
type | integer | Either 0 (role) or 1 (member) |
allow? | string | The bitwise value of all allowed permissions |
deny? | string | The 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
Field | Type | Description |
---|---|---|
webhook_channel_id | snowflake | The 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
Field | Type | Description |
---|---|---|
ringable | boolean | Whether 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
Field | Type | Description |
---|---|---|
region? | string | The 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
Field | Type | Description |
---|---|---|
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
Field | Type | Description |
---|---|---|
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
Field | Type | Description |
---|---|---|
access_token? 1 | string | Access token of a user that has granted your app the gdm.join scope |
nick? | string | Nickname 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
Field | Type | Description |
---|---|---|
consent_status | integer | The new consent status |
Consent Status
Value | Name | Description |
---|---|---|
0 | UNSPECIFIED | The DM isn't a message request |
1 | PENDING | The message request is pending |
2 | ACCEPTED | The message request was accepted |
3 | REJECTED | The 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
Field | Type | Description |
---|---|---|
channel_ids | array[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
Field | Type | Description |
---|---|---|
channel_ids | array[snowflake] | The IDs of the message requests to fetch (1-25) |
Supplemental Message Request Structure
Field | Type | Description |
---|---|---|
channel_id | snowflake | The ID of the message request |
message_preview | message object | The trigger message |
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
Field | Type | Description |
---|---|---|
threads | array[channel object] | The active threads |
members | array[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
Field | Type | Description |
---|---|---|
threads | array[channel object] | The active threads |
members | array[thread member object] | A thread member object for each returned thread the current user has joined |
has_more | boolean | Whether 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
Field | Type | Description |
---|---|---|
before? | ISO8601 timestamp | Get threads before this timestamp |
limit? | integer | Max number of threads to return (2-100, default 50) |
Response Body
Field | Type | Description |
---|---|---|
threads | array[channel object] | The public, archived threads |
members | array[thread member object] | A thread member object for each returned thread the current user has joined |
has_more | boolean | Whether 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
Field | Type | Description |
---|---|---|
before? | ISO8601 timestamp | Get threads before this timestamp |
limit? | integer | Max number of threads to return (2-100, default 50) |
Response Body
Field | Type | Description |
---|---|---|
threads | array[channel object] | The private, archived threads |
members | array[thread member object] | A thread member object for each returned thread the current user has joined |
has_more | boolean | Whether 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
Field | Type | Description |
---|---|---|
before? | snowflake | Get threads before this channel ID |
limit? | integer | Max number of threads to return (2-100, default 50) |
Response Body
Field | Type | Description |
---|---|---|
threads | array[channel object] | The private, archived threads the current user has joined |
members | array[thread member object] | A thread member object for each returned thread the current user has joined |
has_more | boolean | Whether 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
Field | Type | Description |
---|---|---|
name? | string | Search query to look for matching threads (2-100 characters) |
tag? | array[snowflake] | The tag IDs to filter results by |
tag_setting? | string | How to restrict the returned threads by tag (match_some or match_all , default match_some ) |
archived? | boolean | Whether to restrict the search to only active or archived threads (default both) |
sort_by? | string | The sorting algorithm to use |
sort_order? | string | The direction to sort (asc or desc , default desc ) |
limit? | integer | Max number of threads to return (1-25, default 25) |
offset? | integer | Number of threads to skip before returning results |
Thread Sort Type
Value | Description |
---|---|
last_message_time | Sort by the last message sent in the thread (default) |
archive_time | Sort by when the thread was last archived |
relevance | Sort by relevance to the current user |
creation_time | Sort by when the thread was created |
Response Body
Field | Type | Description |
---|---|---|
threads | array[channel object] | The threads that match the search parameters |
members | array[thread member object] | A thread member object for each returned thread the current user has joined |
has_more | boolean | Whether there are potentially additional threads that could be returned on a subsequent call |
total_results | integer | The total number of threads that match the search parameters |
first_messages | array[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
Field | Type | Description |
---|---|---|
name | string | The name of the channel (1-100 characters) |
auto_archive_duration? | integer | Duration in minutes to stop showing in the channel list after inactivity (one of 60, 1440, 4320, 10080, default 4320) |
rate_limit_per_user? | integer | Duration 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 berich
regardless of if you try to set it),provider
,video
, and anyheight
,width
, orproxy_url
values for images.
JSON Params
Field | Type | Description |
---|---|---|
name | string | The name of the channel (1-100 characters) |
auto_archive_duration? | integer | Duration in minutes to stop showing in the channel list after inactivity (one of 60, 1440, 4320, 10080, default 4320) |
rate_limit_per_user? | integer | Duration 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? 1 | integer | the type of thread to create (default PRIVATE_THREAD ) |
invitable? | boolean | Whether 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? 1 | thread-only channel message params object | Contents 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
Field | Type | Description |
---|---|---|
content? | string | The message contents (max 2000 characters) |
embeds? 2 | array[embed object] | Embedded rich content (max 6000 characters, max 10) |
embed? 2 (deprecated) | embed object | Embedded rich content (max 6000 characters), deprecated in favor of embeds |
allowed_mentions? | allowed mention object | Allowed mentions for the message |
components? 2 | array[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 object | The rich presence activity to invite users to |
application_id? | snowflake | The application ID of the activity to create a rich presence invite for (defaults to the primary activity if unspecified) |
flags? | integer | The message's flags (only SUPPRESS_EMBEDS , SUPPRESS_NOTIFICATIONS , and VOICE_MESSAGE can be set) |
files[n]? 1 | file contents | Contents of the file being sent (max 10) |
payload_json? 1 | string | JSON-encoded body of non-file params |
attachments? 1 | array[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
Field | Type | Description |
---|---|---|
thread_ids | array[snowflake] | The IDs of the threads to get post data for |
Response Body
Field | Type | Description |
---|---|---|
threads | object | A mapping of thread IDs to their post data |
Thread Post Data Structure
Field | Type | Description |
---|---|---|
owner | ?guild member object | The owner of the thread |
first_message | ?message object | The 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
Field | Type | Description |
---|---|---|
with_member? | boolean | Whether to include a guild member object for each thread member |
after? | snowflake | Get thread members after this user ID |
limit? | integer | Max 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
Field | Type | Description |
---|---|---|
with_member? | boolean | Whether 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
Field | Type | Description |
---|---|---|
flags? | integer | The user's thread flags flags (all except the first can be set) |
muted? | boolean | Whether the user has muted the thread |
mute_config? | ?mute config object | The 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
Field | Type | Description |
---|---|---|
name | string | The name of the tag (max 20 characters) |
moderated? | boolean | Whether this tag can only be added to or removed from threads by members with the MANAGE_THREADS permission (default false) |
emoji_id? 1 | ?snowflake | The ID of a guild's custom emoji |
emoji_name? 1 | ?string | The 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
Field | Type | Description |
---|---|---|
name | string | The name of the tag (max 20 characters) |
moderated? | boolean | Whether this tag can only be added to or removed from threads by members with the MANAGE_THREADS permission (default false) |
emoji_id? 1 | ?snowflake | The ID of a guild's custom emoji |
emoji_name? 1 | ?string | The 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.