Channels Resource

Represents a guild or DM 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.

** For threads created before July 1, 2022, the message count is inaccurate when it's greater than 50.

* The GUILD_MEDIA channel type is still in active development. Avoid implementing any features that are not documented here, since they are subject to change without notice!

Over the Gateway, a client will receive a channel object with obfuscated metadata for guild channels it does not have permission to view. Permission to view a channel is defined by having VIEW_CHANNEL permission on a channel or by being connected to a voice channel. Channel categories are viewable if any of their child channels are viewable.

Over the HTTP API, channels that a client cannot view will be omitted from the response entirely.

Obfuscated channels are dispatched through the normal Channel Create and Channel Update gateway events, including within the channel list of a Guild Create event.

To reliably detect whether a channel object has been obfuscated, check whether its flags field has the CHANNEL_OBFUSCATED channel flag (1 << 17) set. Do not rely on inspecting name or any other obfuscated field. The permission_overwrites for an obfuscated channel will contain only one entry denying VIEW_CHANNEL for the guild's @everyone role.

When a bot user regains visibility into a previously obfuscated channel (for example, a permission overwrite change, a change to the bot user's roles, a change to a role's permissions, or the bot user joining a voice channel it previously couldn't see), the Gateway dispatches a Channel Update event containing the full, unobfuscated channel data. If the channel's parent category was also obfuscated (because the bot user couldn't see it either), that category also receives a Channel Update event with its full, unobfuscated data.

Interactions are built through a separate path that does not apply obfuscation, so an app always receives full channel data in interaction payloads for channels it can act on.

{
  "id": "41771983423143937",
  "guild_id": "41771983423143937",
  "name": "general",
  "type": 0,
  "position": 6,
  "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",
  "default_auto_archive_duration": 60
}

Bots can post or publish messages in this type of channel if they have the proper permissions.

{
  "id": "41771983423143937",
  "guild_id": "41771983423143937",
  "name": "important-news",
  "type": 5,
  "position": 6,
  "permission_overwrites": [],
  "nsfw": true,
  "topic": "Rumors about Half Life 3",
  "last_message_id": "155117677105512449",
  "parent_id": "399942396007890945",
  "default_auto_archive_duration": 60
}

{
  "id": "155101607195836416",
  "last_message_id": "174629835082649376",
  "type": 2,
  "name": "ROCKET CHEESE",
  "position": 5,
  "parent_id": null,
  "bitrate": 64000,
  "user_limit": 0,
  "rtc_region": null,
  "guild_id": "41771983423143937",
  "permission_overwrites": [],
  "rate_limit_per_user": 0,
  "nsfw": false,
}

{
  "last_message_id": "3343820033257021450",
  "type": 1,
  "id": "319674150115610528",
  "recipients": [
    {
      "username": "test",
      "discriminator": "9999",
      "id": "82198898841029460",
      "avatar": "33ecab261d4681afa4d85a04691c4a01"
    }
  ]
}

{
  "name": "Some test channel",
  "icon": null,
  "recipients": [
    {
      "username": "test",
      "discriminator": "9999",
      "id": "82198898841029460",
      "avatar": "33ecab261d4681afa4d85a04691c4a01"
    },
    {
      "username": "test2",
      "discriminator": "9999",
      "id": "82198810841029460",
      "avatar": "33ecab261d4681afa4d85a10691c4a01"
    }
  ],
  "last_message_id": "3343820033257021450",
  "type": 3,
  "id": "319674150115710528",
  "owner_id": "82198810841029460"
}

{
  "permission_overwrites": [],
  "name": "Test",
  "parent_id": null,
  "nsfw": false,
  "position": 0,
  "guild_id": "290926798629997250",
  "type": 4,
  "id": "399942396007890945"
}

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

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

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.

** The member field is only present when with_member is set to true when calling List Thread Members or Get Thread Member.

An object that specifies the emoji to use as the default way to react to a forum post. Exactly one of emoji_id and emoji_name must be set.

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.

/channels/{channel.id}

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

/channels/{channel.id}

Update a channel's settings. Returns a channel on success, and a 400 BAD REQUEST on invalid parameters.

Fires a Channel Update Gateway event.

Requires the MANAGE_CHANNELS permission for the guild. 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 permission overwrites, the MANAGE_ROLES permission is required. Only permissions your bot has in the guild or parent channel (if applicable) can be allowed/denied (unless your bot has a MANAGE_ROLES overwrite in the channel).

* For voice channels, normal servers can set bitrate up to 96000, servers with Boost level 1 can set up to 128000, servers with Boost level 2 can set up to 256000, and servers with Boost level 3 or the VIP_REGIONS guild feature can set up to 384000. For stage channels, bitrate can be set up to 64000.

** In each overwrite object, the allow and deny keys can be omitted or set to null, which both default to "0".

When setting archived to false, when locked is also false, only the SEND_MESSAGES permission is required.

Otherwise, requires the MANAGE_THREADS permission. Fires a Thread Update Gateway event. Requires the thread to have archived set to false or be set to false in the request.

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

Set 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. Fires a Voice Channel Status Update Gateway event.

/channels/{channel.id}

Delete a channel, or close 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 Gateway event (or Thread Delete if the channel was a thread).

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

Edit the channel permission overwrites for a user or role in a channel. Only usable for guild channels. Requires the MANAGE_ROLES permission. Only permissions your bot has in the guild or parent channel (if applicable) can be allowed/denied (unless your bot has 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.

/channels/{channel.id}/invites

Returns a list of invite objects (with invite metadata) for the channel. Only usable for guild channels. Requires the MANAGE_CHANNELS permission.

/channels/{channel.id}/invites

Create a new invite object for the channel. Only usable for guild channels. Requires the CREATE_INSTANT_INVITE permission. All JSON parameters for this route are optional, however the request body is not. If you are not sending any fields, you still have to send an empty JSON object ({}). Returns an invite object. Fires an Invite Create Gateway event.

* Requires multipart/form-data as the content type with other parameters as form fields in the multipart body. Uploading a file with invalid user IDs will result in a 400 with the invalid IDs described. Duplicate user IDs in the file will be ignored.

** target_user_ids and target_users_file are mutually exclusive, only one can be sent at a time.

*** Requires the MANAGE_ROLES permission and cannot assign roles with higher permissions than the sender.

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

Delete 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

/channels/{channel.id}/followers

Follow an Announcement 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.

/channels/{channel.id}/typing

Post a typing indicator for the specified channel, which expires after 10 seconds. Returns a 204 empty response on success. Fires a Typing Start Gateway event.

Generally bots should not use this route. However, if a bot is responding to a command and expects the computation to take a few seconds, this endpoint may be called to let the user know that the bot is processing their message.

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

Adds a recipient to a Group DM using their access token.

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

Removes a recipient from a Group DM.

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

Creates a new thread from an existing message. Returns a channel on success, and a 400 BAD REQUEST on invalid parameters. 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_ANNOUNCEMENT channel, creates a ANNOUNCEMENT_THREAD. Does not work on a GUILD_FORUM or a GUILD_MEDIA channel. The id of the created thread will be the same as the id of the source message, and as such a message can only have a single thread created from it.

/channels/{channel.id}/threads

Creates a new thread that is not connected to an existing message. Returns a channel on success, and a 400 BAD REQUEST on invalid parameters. Fires a Thread Create Gateway event.

* type currently defaults to PRIVATE_THREAD in order to match the behavior when thread documentation was first published. In a future API version this will be changed to be a required field, with no default.

/channels/{channel.id}/threads

Creates a new thread in a forum or a media channel, and sends a message within the created thread. Returns a channel, with a nested message object, on success, and a 400 BAD REQUEST on invalid parameters. Fires a Thread Create and Message Create Gateway event.

• 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 25 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.
• Examples for file uploads are available in Uploading Files.
• Files must be attached using a multipart/form-data body as described in Uploading Files.
• Note that when sending a message, you must provide a value for at least one of content, embeds, sticker_ids, components, or files[n].

* At least one of content, embeds, sticker_ids, components, or files[n] is required.

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

/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 if the member is successfully added or was already a member of the thread. Fires a Thread Members Update Gateway event.

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

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

Removes another 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.

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

Returns a thread member object for the specified user if they are a member of the thread, returns a 404 response otherwise.

When with_member is set to true, the thread member object will include a member field containing a guild member object.

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

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

/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_ANNOUNCEMENT channel returns threads of type ANNOUNCEMENT_THREAD. Threads are ordered by archive_timestamp, in descending order. Requires the READ_MESSAGE_HISTORY permission.

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

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