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

¹ 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.

² 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.

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

⁴ Only included in the Gateway Guild object.

Channel Type

Channel Flags

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

Video Quality Mode

Forum Layout Type

Sort Order Type

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
    }
  ]
}

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
    },
    {
      "id": "211270674482724864",
      "username": "11pixels",
      "avatar": "40e250de9c74346c480e7e16da242b47",
      "discriminator": "0",
      "public_flags": 4194880,
      "banner": "785814ab5375e10deafe9e7de256dd0e",
      "accent_color": 47615,
      "global_name": "12pixels",
      "avatar_decoration_data": 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

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

² 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"
    }
  ]
}

Permission Overwrite Object

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

Permission Overwrite Structure

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

Permission Overwrite Type

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

Thread Member Object

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

Thread Member Structure

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

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

³ 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

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

¹ 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

¹ 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

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

Endpoints

Get Private Channels

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

Get DM Channel

Returns an existing DM channel object with a user.

Create Private Channel

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

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

Get Guild Channels

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

Query String Params

Get Guild Top Read Channels

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

Create Guild Channel

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

¹ 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.

² Only the name field is required.

Modify Guild Channel Positions

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

Get Channel

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

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.

¹ 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.

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

Delete Channel

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

Delete Read State

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

Modify Channel 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

Modify Channel Permissions

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

Delete Channel Permission

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

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

Trigger Typing Indicator

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

Get Call Eligibility

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

Response Body

Modify Call

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

JSON Params

Ring Channel Recipients

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

Stop Ringing Channel Recipients

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

Add Channel Recipient

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

JSON Params

¹ Only required for OAuth2 requests.

Remove Channel Recipient

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

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

JSON Params

Consent Status

Reject Message Request

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

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

Get Supplemental Message Request Data

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

Query String Params

Supplemental Message Request Structure

Get Guild Active Threads

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

Response Body

Get Active Threads

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

Response Body

Get Public Archived Threads

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

Response Body

Get Private Archived Threads

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

Response Body

Get Joined Private Archived Threads

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

Response Body

Search Threads

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

Query String Params

Thread Sort Type

Response Body

Create Thread from Message

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

Create Thread

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

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

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

Thread-Only Channel Message Params Structure

¹ See Uploading Files for details.

² Cannot be used by user accounts.

Get Channel 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

Response Body

Thread Post Data Structure

Example Response

{
  "threads": {
    "1075957063890509894": {
      "first_message": null,
      "owner": null
    }
  }
}

Get Thread Members

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

Query String Params

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

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

Query String Params

Join Thread

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

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

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

Leave Thread

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

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

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

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

Modify Channel Tag

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

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

Delete Channel Tag

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.