discord.js Guide

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 ThreadChannel#isThread()open in new window type guard to make sure a channel is a ThreadChannelopen in new window!

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

Creating and deleting threads

Threads are created and deleted using the ThreadManageropen in new window of a text or news channel. To create a thread you call the ThreadManager#create()open in new window 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()open in new window 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()open in new window 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()open in new window;

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()open in new window 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()open in new window 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 can be created with the ThreadManager#create()open in new window 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

They can also be created from an existing message with the Message#startThread()open in new window method, but will be "orphaned" if that message is deleted.

const thread = await message.startThread({
	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

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()open in new window and pass in GUILD_PRIVATE_THREAD as the type:

const thread = await channel.threads.create({
	name: 'mod-talk',
	autoArchiveDuration: 60,
	type: 'GUILD_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()open in new window 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()open in new window:

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

Sending messages to threads with webhooks

It is possible for a webhook built on the parent channel to send messages to the channel's threads. For the purpose of this example, it is assumed a single webhook already exists for that channel. If you wish to learn more about webhooks, see our webhook guide.

const webhooks = await channel.fetchWebhooks();
const webhook = webhooks.first();

await webhook.send({
	content: 'Look ma! I\'m in a thread!',
	threadId: '123456789012345678',
});
1
2
3
4
5
6
7

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