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.

A guild or private channel within Discord.

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

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

{
  "id": "399942396007890945",
  "type": 4,
  "name": "lounge",
  "position": 0,
  "flags": 0,
  "parent_id": null,
  "guild_id": "41771983423143937",
  "permission_overwrites": []
}

{
  "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
}

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
}

{
  "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
}

{
  "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
}

{
  "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
}

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

{
  "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"
}

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": []
}

A channel referenced in an invite or message.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Returns an existing DM channel object with a user.

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.

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

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

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

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.

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

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:

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.

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

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

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.

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.

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.

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.

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

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. Fires a Webhooks Update Gateway event for the target channel.

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

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

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

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.

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.

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

¹ Only required for OAuth2 requests.

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.

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

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

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.

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.

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.

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

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.

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.

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

¹ See Uploading Files for details.

² Cannot be used by user accounts.

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

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

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

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.

Returns a thread member object for the specified user if they are a member of the 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.

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.

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.

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.

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.

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.

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

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.

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

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.