Threads

Threads can be thought of as temporary sub-channels inside an existing channel, to help better organize conversation in a busy channel.

TIP

You can use the isThread() type guard to make sure a channel is a ThreadChannel!

Threads introduce a number of new gateway events, which are listed below:

Client#threadCreate: Emitted whenever a thread is created or when the client user is added to a thread.
Client#threadDelete: Emitted whenever a thread is deleted.
Client#threadUpdate: Emitted whenever a thread is updated (e.g. name change, archive state change, locked state change).
Client#threadListSync: Emitted whenever the client user gains access to a text or news channel that contains threads.
Client#threadMembersUpdate: Emitted whenever members are added or removed from a thread. Requires GUILD_MEMBERS privileged intent.
Client#threadMemberUpdate: Emitted whenever the client user's thread member is updated.

Creating and deleting threads

Threads are created and deleted using the ThreadManager of a text or news channel. To create a thread you call the ThreadManager#create() method:

const thread = await channel.threads.create({
	name: 'food-talk',
	autoArchiveDuration: 60,
	reason: 'Needed a separate thread for food',
});

console.log(`Created thread: ${thread.name}`);

1
2
3
4
5
6
7

To delete a thread, use the ThreadChannel#delete() method:

const thread = channel.threads.cache.find(x => x.name === 'food-talk');
await thread.delete();

1
2

Joining and leaving threads

To join your client to a ThreadChannel, use the ThreadChannel#join() method:

const thread = channel.threads.cache.find(x => x.name === 'food-talk');
if (thread.joinable) await thread.join();

1
2

And to leave one, use ThreadChannel#leave();

const thread = channel.threads.cache.find(x => x.name === 'food-talk');
await thread.leave();

1
2

Archiving, unarchiving, and locking threads

A thread can be either active or archived. Changing a thread from archived to active is referred to as unarchiving the thread. Threads that have locked set to true can only be unarchived by a member with the MANAGE_THREADS permission.

Threads are automatically archived after inactivity. "Activity" is defined as sending a message, unarchiving a thread, or changing the auto-archive time.

To archive or unarchive a thread, use the ThreadChannel#setArchived() method and pass in a boolean parameter:

const thread = channel.threads.cache.find(x => x.name === 'food-talk');
await thread.setArchived(true); // archived
await thread.setArchived(false); // unarchived

1
2
3

This same principle applies to locking and unlocking a thread via the ThreadChannel#setLocked() method:

const thread = channel.threads.cache.find(x => x.name === 'food-talk');
await thread.setLocked(true); // locked
await thread.setLocked(false); // unlocked

1
2
3

WARNING

Archived threads can't be locked!

Public and private threads

Public threads are viewable by everyone who can view the parent channel of the thread. Public threads must be created from an existing message, but can be "orphaned" if that message is deleted. The created thread and the message it originated from will share the same ID. The type of thread created matches the parent channel's type.

Private threads behave similar to Group DMs, but in a Guild. Private threads can only be created on text channels.

To create a private thread, use ThreadManager#create() and pass in private_thread as the type:

const thread = await channel.threads.create({
	name: 'mod-talk',
	autoArchiveDuration: 60,
	type: 'private_thread',
	reason: 'Needed a separate thread for moderation',
});

console.log(`Created thread: ${thread.name}`);

1
2
3
4
5
6
7
8

Adding and removing members

You can add and remove members to and from a thread channel.

To add a member to a thread, use the ThreadMemberManager#add() method:

const thread = channel.threads.cache.find(x => x.name === 'food-talk');
await thread.members.add('140214425276776449');

1
2

And to remove a member from a thread, use ThreadMemberManager#remove():

const thread = channel.threads.cache.find(x => x.name === 'food-talk');
await thread.members.remove('140214425276776449');

1
2

And that's it! Now you know all there is to know on working with threads using discord.js!

# Threads

# Thread related gateway events

# Creating and deleting threads

# Joining and leaving threads

# Archiving, unarchiving, and locking threads

# Public and private threads