diff --git a/apps/guide/src/content/04-popular-topics/03-threads.mdx b/apps/guide/src/content/04-popular-topics/03-threads.mdx new file mode 100644 index 000000000..5557b42f6 --- /dev/null +++ b/apps/guide/src/content/04-popular-topics/03-threads.mdx @@ -0,0 +1,202 @@ +--- +title: Threads +category: Popular topics +--- + +# Threads + +Threads can be thought of as temporary sub-channels inside an existing channel to help better organize conversations in a busy channel. + +## Thread related gateway events + + + You can use the type guard to make sure a + channel is a ! + + +Threads introduce a number of new gateway events, which are listed below: + +- : Emitted whenever a thread is created or when the + client user is added to a thread. +- : Emitted whenever a thread is deleted. +- : Emitted whenever a thread is updated (e.g. name + change, archive state change, locked state change). +- : Emitted whenever the client user gains access to + a text or announcement channel that contains threads. +- : Emitted whenever members are added or + removed from a thread. Requires GuildMembers privileged intent. +- : Emitted whenever the client user's thread + member is updated. + +## Creating and deleting threads + +Threads are created and deleted using the of a text or announcement channel. +To create a thread, you call the method: + + + +```js +import { ThreadAutoArchiveDuration } from 'discord.js'; + +const thread = await channel.threads.create({ + name: 'food-talk', + autoArchiveDuration: ThreadAutoArchiveDuration.OneHour, + reason: 'Needed a separate thread for food', +}); + +console.log(`Created thread: ${thread.name}`); +``` + + + +They can also be created from an existing message with the method, but will be "orphaned" if that message is deleted. + + + +```js focus=3[22:42] +import { ThreadAutoArchiveDuration } from 'discord.js'; + +const thread = await message.startThread({ + name: 'food-talk', + autoArchiveDuration: ThreadAutoArchiveDuration.OneHour, + reason: 'Needed a separate thread for food', +}); + +console.log(`Created thread: ${thread.name}`); +``` + + + +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. + +To delete a thread, use the method: + + + +```js focus=2 +const thread = channel.threads.cache.find((x) => x.name === 'food-talk'); +if (thread.manageable) await thread.delete(); +``` + + + +## Joining and leaving threads + +To subscribe your client to a thread, use the method: + + + +```js focus=2 +const thread = channel.threads.cache.find((x) => x.name === 'food-talk'); +if (thread.joinable) await thread.join(); +``` + + + +And to leave one, use the method: + + + +```js focus=2 +const thread = channel.threads.cache.find((x) => x.name === 'food-talk'); +await thread.leave(); +``` + + + +## 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 _`ManageThreads`_ 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 method and pass in a boolean parameter: + + + +```js focus=2,3 +const thread = channel.threads.cache.find((x) => x.name === 'food-talk'); +await thread.setArchived(true); // Archived. +await thread.setArchived(false); // Unarchived. +``` + + + +This same principle applies to locking and unlocking a thread via the method: + + + +```js focus=2,3 +const thread = channel.threads.cache.find((x) => x.name === 'food-talk'); +await thread.setLocked(true); // Locked. +await thread.setLocked(false); // Unlocked. +``` + + + +## Private threads + +Public threads are viewable by everyone who can view the parent channel of the thread. Private threads, however, are only viewable to those who are invited or have the _`ManageThreads`_ permission. Private threads can only be created on text channels. + +To create a private thread, use the method and pass in _`ChannelType.PrivateThread`_ as the _`type`_: + + + +```js focus=1[10:21],6 +import { ChannelType, ThreadAutoArchiveDuration } from 'discord.js'; + +const thread = await channel.threads.create({ + name: 'mod-talk', + autoArchiveDuration: ThreadAutoArchiveDuration.OneHour, + type: ChannelType.PrivateThread, + reason: 'Needed a separate thread for moderation', +}); + +console.log(`Created thread: ${thread.name}`); +``` + + + +## Adding and removing members + +You can add members to a thread with the method. The thread must be unarchived and you must be able to send messages in it. + + + +```js focus=2 +const thread = channel.threads.cache.find((x) => x.name === 'food-talk'); +await thread.members.add('12345678901234567'); +``` + + + +You can remove members from a thread with the method. The thread must be unarchived and you must have the _`ManageThreads`_ permission unless the thread is private and you are the owner of it. + + + +```js focus=2 +const thread = channel.threads.cache.find((x) => x.name === 'food-talk'); +await thread.members.remove('12345678901234567'); +``` + + + +## 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](./webhooks). + + + +```js focus=4:7 +const webhooks = await channel.fetchWebhooks(); +const webhook = webhooks.first(); + +await webhook.send({ + content: "Look ma! I'm in a thread!", + threadId: '123456789012345678', +}); +``` + + + +And that's it! Now you know all there is to know on working with threads using discord.js! diff --git a/apps/guide/src/content/05-additional-info/01-async-await.mdx b/apps/guide/src/content/05-additional-info/01-understanding-async-await.mdx similarity index 100% rename from apps/guide/src/content/05-additional-info/01-async-await.mdx rename to apps/guide/src/content/05-additional-info/01-understanding-async-await.mdx