feat(guide): Add threads (#9430)

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
+
+<Alert title="Tip" type="info">
+	You can use the <DocsLink type="class" parent="BaseChannel" symbol="isThread" brackets /> type guard to make sure a
+	channel is a <DocsLink type="class" parent="ThreadChannel" />!
+</Alert>
+
+Threads introduce a number of new gateway events, which are listed below:
+
+- <DocsLink type="class" parent="Client" symbol="e-threadCreate" />: Emitted whenever a thread is created or when the
+  client user is added to a thread.
+- <DocsLink type="class" parent="Client" symbol="e-threadDelete" />: Emitted whenever a thread is deleted.
+- <DocsLink type="class" parent="Client" symbol="e-threadUpdate" />: Emitted whenever a thread is updated (e.g. name
+  change, archive state change, locked state change).
+- <DocsLink type="class" parent="Client" symbol="e-threadListSync" />: Emitted whenever the client user gains access to
+  a text or announcement channel that contains threads.
+- <DocsLink type="class" parent="Client" symbol="e-threadMembersUpdate" />: Emitted whenever members are added or
+  removed from a thread. Requires <code>GuildMembers</code> privileged intent.
+- <DocsLink type="class" parent="Client" symbol="e-threadMemberUpdate" />: Emitted whenever the client user's thread
+  member is updated.
+
+## Creating and deleting threads
+
+Threads are created and deleted using the <DocsLink type="class" parent="GuildTextThreadManager" /> of a text or announcement channel.
+To create a thread, you call the <DocsLink type="class" parent="GuildTextThreadManager" symbol="create" brackets /> method:
+
+<CH.Code>
+
+```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}`);
+```
+
+</CH.Code>
+
+They can also be created from an existing message with the <DocsLink type="class" parent="Message" symbol="startThread" brackets /> method, but will be "orphaned" if that message is deleted.
+
+<CH.Code>
+
+```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}`);
+```
+
+</CH.Code>
+
+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 <DocsLink type="class" parent="ThreadChannel" symbol="delete" brackets /> method:
+
+<CH.Code>
+
+```js focus=2
+const thread = channel.threads.cache.find((x) => x.name === 'food-talk');
+if (thread.manageable) await thread.delete();
+```
+
+</CH.Code>
+
+## Joining and leaving threads
+
+To subscribe your client to a thread, use the <DocsLink type="class" parent="ThreadChannel" symbol="join" brackets /> method:
+
+<CH.Code>
+
+```js focus=2
+const thread = channel.threads.cache.find((x) => x.name === 'food-talk');
+if (thread.joinable) await thread.join();
+```
+
+</CH.Code>
+
+And to leave one, use the <DocsLink type="class" parent="ThreadChannel" symbol="leave" brackets /> method:
+
+<CH.Code>
+
+```js focus=2
+const thread = channel.threads.cache.find((x) => x.name === 'food-talk');
+await thread.leave();
+```
+
+</CH.Code>
+
+## 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 <DocsLink type="class" parent="ThreadChannel" symbol="setArchived" brackets /> method and pass in a boolean parameter:
+
+<CH.Code>
+
+```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.
+```
+
+</CH.Code>
+
+This same principle applies to locking and unlocking a thread via the <DocsLink type="class" parent="ThreadChannel" symbol="setLocked" brackets /> method:
+
+<CH.Code>
+
+```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.
+```
+
+</CH.Code>
+
+## 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 <DocsLink type="class" parent="GuildTextThreadManager" symbol="create" brackets /> method and pass in _`ChannelType.PrivateThread`_ as the _`type`_:
+
+<CH.Code>
+
+```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}`);
+```
+
+</CH.Code>
+
+## Adding and removing members
+
+You can add members to a thread with the <DocsLink type="class" parent="ThreadMemberManager" symbol="add" brackets /> method. The thread must be unarchived and you must be able to send messages in it.
+
+<CH.Code>
+
+```js focus=2
+const thread = channel.threads.cache.find((x) => x.name === 'food-talk');
+await thread.members.add('12345678901234567');
+```
+
+</CH.Code>
+
+You can remove members from a thread with the <DocsLink type="class" parent="ThreadMemberManager" symbol="remove" brackets /> 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.
+
+<CH.Code>
+
+```js focus=2
+const thread = channel.threads.cache.find((x) => x.name === 'food-talk');
+await thread.members.remove('12345678901234567');
+```
+
+</CH.Code>
+
+## 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).
+
+<CH.Code>
+
+```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',
+});
+```
+
+</CH.Code>
+
+And that's it! Now you know all there is to know on working with threads using discord.js!