Skip to main content


Threads are Messageable objects, and can be thought of as sub-channels inside existing channels. They allow organization of multiple topics in a channel by temporarily giving them a separate space.

Creating and deleting threads

A thread can be created by using the create_thread() method on a Message or TextChannel object.
# Using the 'Message' object
message = channel.fetch_message(1234567890)
await message.create_thread(
name="This message will act as the thread's starting message.",

# Using the 'TextChannel' object
channel = bot.get_channel(...)
await channel.create_thread(
name="This thread requires a starting message to be specified.",

In order to delete a thread, you can use the delete() method on the Thread object.
thread = channel.get_thread(...)  # You can also use bot.get_channel(...)

await thread.delete()

Joining and leaving threads

Both joining and leaving a thread require you to have a Thread object, on which you can use the join() and leave() methods for the respective action.
thread = channel.get_thread(...)  # You can also use bot.get_channel(...)

# Joining a thread.
await thread.join()

# Leaving a thread.
await thread.leave()

It is recommended to use a try-except loop here, in case that the thread is not joinable by the bot user; this can be due to missing permissions.

Archiving, unarchiving and locking threads

Archiving a thread essentially makes it "read-only" for non-moderators - where they can view older messages, but not send messages themselves. Locked threads can only be unarchived by users who have the manage_threads permission.

Threads have an auto-archive duration - a period of time after which the thread is archived automatically without being configured by a moderator. This duration can also be set by a bot user while creating or editing a thread.
thread = channel.get_thread(...)

await thread.edit(auto_archive_duration=60)

Configuring a thread to be archived, unarchived or locked can be done using the edit() method, via the archived and locked parameters. Both of these attributes accept a boolean value.
thread = channel.get_thread(...)

# Archiving a thread
await thread.edit(archived=True) # Set to 'False', to unarchive the thread

# Locking a thread
await thread.edit(locked=True)

Public and private threads

Public threads are accessible to all members that can view the thread's parent channel. Such threads can be created using the create_thread() method, as covered in a previous section.

Private threads are those which are only accessible to moderators and the members invited by the thread creator. A private thread can be created by specifying the type in the create_thread() method as private_thread.
channel = bot.get_channel(...)

await channel.create_thread(
name="Thread Title",

A private thread can only be created on a TextChannel object. The type that can be specified under create_thread() can be public_thread, private_thread or news_thread.

Threads introduce some new gateway events, which are listed below. You can find more information on these in the documentation.