# Getting started with Thread-Watcher Let's get your threads organized! Thread-Watcher is a Discord bot aiming to be your go to toolbox for Discord threads or forum channels. It has been used in thousands of servers since 2021 to make sure threads are where you want them, without randomly disappearing. Thread-Watcher has shifted to encompass any feature related to threads but keeping threads alive forever remains the **core feature** of the bot. The goal of this documentation is to provide you with everything you will need to get Thread-Watcher set up and working in your Discord server. Looking for self hosting documentation? Check out the [GitHub repo](https://github.com/ffamilyfriendly/thread-watcher). ### Quick start I get it, you just want your threads to stay visible without my rambling. Here's a super quick step-by-step guide on how to do just that with Thread-Watcher! {% stepper %} {% step %} ### Invite the bot to your server Haven't invited the bot yet? [Invite Thread-Watcher to your server](https://threadwatcher.xyz/invite) {% endstep %} {% step %} ### Watch your threads Thread-Watcher needs you to select ("watch") threads that it will keep visible. There's plenty of ways to do this, the easiest being [`/watch`](broken://pages/wvTmIYZ9zipUaqIlbSwH) for watching individual threads or [`/batch`](broken://pages/wvTmIYZ9zipUaqIlbSwH) for watching multiple threads at once. {% endstep %} {% step %} ### Done 🎊 That's it! Your watched threads will now stay visible forever. {% endstep %} {% endstepper %} While this is enough to get you started, I suggest browsing the documentation to discover even more effective ways to use Thread-Watcher! # Core Features The core features of Thread-Watcher is the ability to select ("watch") threads and forum posts, hindering discord from automatically hiding or archiving them. ### What is being solved? Consider the attached image. By default the two threads, `Cooking 🧑🍳` and `I did a thing` will get hidden from underneath the channel after the "Hide After Inactivity" timeframe has passed without a message being sent in the threads.
a Discord screenshot showing a forum channel called "member-projects" with two threads shown attached to the channel
This is likely intended by Discord to keep threads nice and tidy, to automatically "clean up" stale threads so your channel list is not filled with old conversations. However, this gets annoying quick if you are using threads for anything where long periods of inactivity is common. Especially frustrating is that there's no option to disable this automatic hiding of threads and that the max timeframe you can pick is 1 week. ### How is Thread-Watcher solving it? Thread-Watcher will automatically "bump" your watched threads periodically to keep discord from hiding them! This is done by editing the thread which is completely silent, no weird notifications or ghost messages. ### Don't want bumps? If you don't mind the threads disappearing from underneath the channel and just want the bot to make sure they're never archived you can set the Bump Behavior option to `Un-Archive only`
# Commands This is a quick and dirty list of all commands featured on the core module of Thread-Watcher. You can learn more about each command by reading it's description and options directly in the Discord client itself. | Name | Description | Required Permissions | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `/watch` | used to toggle the watch status of an individual thread | User requires `Manage Threads` | | `/batch` | used to watch or unwatch multiple threads in a channel, category, or the whole server at once. Features [advanced filtering](/features/core-features/advanced-filtering) for more selective... selections? | User & bot requires `Manage Threads` | | `/config` | Used to configure Thread-Watcher settings | User requires `Manage Server` | | `/info` | provides some general information about the bot | | | `/list` | Used to list all watched threads and monitors. | No permissions required. However, it only lists watched threads that the user can actually view. | | `/monitor add` | Used to add or edit [monitors](/features/core-features/monitors) | User requires `Manage Threads` | | `/monitor add` | Used to remove monitors | User requires `Manage Threads` | ### User Permissions By default Thread-Watcher checks the permission a user has in the channel that the command is ran to decide whether or not a user is allowed to run the command. However, you can configure this yourself using [Slash Command Permissions](https://discord.com/blog/slash-commands-permissions-discord-apps-bots). Remember to enable the `Use Discord Command Permissions` setting in your Thread-Watcher configuration for Thread-Watcher to respect these new permissions!
# Monitors Set it, forget it! The Monitors feature let's you watch all future threads or posts created in a channel, a category, *or the whole server*! Thread-Watcher will monitor your server for any new threads, or changes to old ones, and automatically watch them for you. Monitors fully support [**Conditional Filters**](/features/core-features/advanced-filtering) which allows you to narrow down which threads are watched. You can require a thread has a specific format in its name, the thread creator has a specific role, or that the thread needs a specific tag attached. Thread-Watcher will continue to monitor the thread for any updates to it. If a thread no longer matches the filters, it will un-watch it. # Advanced Filtering Advanced filtering can be used on `/batch` and `/auto` (and [monitors](/features/core-features/monitors) created on the web) to conditionally select what threads to watch or unwatch. Only threads that match **ALL** of the selected filters will be watched. Do note that if no value is configured for a filter (such as roles) that filter will be skipped. ### Roles Select one or more roles that the owner of the thread must have for Thread-Watcher to watch the thread. ### Tags Select one or more forum tags that the post must have for Thread-Watcher to watch it. \ This is only accessible for forum channels ### Regex You can use a [regex](https://en.wikipedia.org/wiki/Regular_expression) to select only threads whose name follow a certain pattern. More text needs to be added here tbh. Gotta do boring doc work before launching V3 #### Rejected Regex To protect the bot from [ReDos](https://en.wikipedia.org/wiki/ReDoS) attacks we proactively screen any regex inputs. This might unfortunately erroneously catch some valid regex patterns. # Tickets tickets are coming soon stg # Commands This is a quick and dirty list of all commands featured on the ticket module of Thread-Watcher. You can learn more about each command by reading it's description and options directly in the Discord client itself. | Name | Description | Required Permissions | | -------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | | `/ticket assign` | Assign a ticket to a user | User needs to have one of the `Assigned Roles` | | `/ticket new-note` | Add a mod note to the ticket. This is only visible by other users with one of the assigned roles | User needs to have one of the `Assigned Roles` | | `/ticket resolve` | Marks the ticket as resolved. This cannot be undone | User needs to have one of the `Assigned Roles` or be the ticket creator | | `/ticket view-notes` | Shows you the last 10 mod notes of this ticket | User needs to have one of the `Assigned Roles` | # Ticket Panels Ticket panels are your users entry point into creating a ticket Thread-Watcher features a ticket system which is threads based and integrated with the core features. The ticket panel system is designed to be highly customizable, giving you great flexibility in making ticket flows optimized for your server. ## Panel Configuration ### Assigned Roles These are the roles that are given access to management of any tickets of this panel. These roles will be pinged upon ticket creation and can use any and all [Ticket Commands](/features/tickets/commands), read and create mod notes, and access the transcript of the ticket. Assigned Roles can be dynamically assigned on a case-by-case basis, more information further down. ### Assigned Channel This is the channel that the ticket will be created in, and also the channel the Panel Embed will be sent in. Thread-Watcher will try to create private threads if possible, but if the assigned channel is a forum channel it will create a public forum post. Like assigned roles, the assigned channel can also be dynamically assigned on a case-by-case basis. ### Panel embed customization Each panel has one "Panel Embed" which is the message that your users interact with to start the ticket pipeline. You can edit the title, description, colour, and add fields to this embed. This allows you to create an informative starting point for the users. **Please note:** Thread-Watcher will automatically add a small section to your embed informing the user of Thread-Watcher's [privacy policy](https://threadwatcher.xyz/policies/privacy-policy) and [terms of service](https://threadwatcher.xyz/policies/terms-of-service) to the embed. This disclaimer cannot be turned off or otherwise removed. Currently there's no way to change the footer or add images, but this might be added later.
To start the ticket you've got 2 options: * a button * a select menu ### Resolve Embed customization This is the message that is sent when the ticket is marked as resolved and similar to the previous section in behavior. However, this embed allows you to input [variables](/features/tickets/templating-language) by typing `{{variable_name}}`.
### Watch Ticket a toggle indicating whether or not you want Thread-Watcher to watch the created ticket thread. This is turned on by default, but can be toggled off for whatever reason. ### Summarize Ticket toggle for AI-powered summaries of the ticket. If enabled, Thread-Watcher will read messages within the thread to create incremental summaries of that has been happening. This allows you a quick and easy way to get a hint what's been going on without having to backread. When a ticket is marked as "Resolved", Thread-Watcher will create a "master summary" that briefly details the whole ticket. Thread-Watcher uses `Mistral-Small` to generate the summaries and is set to not allow any data to be used for training. It is your duty as the server administrator to ensure your users are informed of Thread-Watcher's [Privacy Policy](https://threadwatcher.xyz/policies/privacy-policy). ### Close Method this tells Thread-Watcher what to do when a ticket is resolved. * Nothing: the bot does nothing with the thread. * Lock: the bot locks the ticket thread * Delete: the bot deletes the ticket thread If configured to delete the thread, the "Resolve Embed" will be sent to the user in DMs if possible. ## Create a ticket pipeline To actually start accepting tickets, you need to define a ticket "pipeline". You do this by dragging and dropping [Modules](/features/tickets/modules) which will guide the user thru the process and allowing you to gather any information you might need from the user along the way. This might seem harrowing if you've not used any similar tool before, which is why Thread-Watcher comes with 2 template pipelines that allow you to try out Thread-Watcher tickets without delay.
## Deleting a panel you may at any time delete a panel. Any active tickets created by this panel will continue to work but with default panel settings. This means the user will get a default embed when the ticket is resolved, the ticket will be locked when resolved, and messages will be used to generate a summary. Relying on default settings is not optimal, and I suggest you never delete a panel with active tickets even if it's technically possible. # Modules As mentioned in the previous page, a ticket is created by the user first going thru a "pipeline" of modules defined by you. These modules are ran in order from top to bottom and culminates in a ticket being created! Modules can be configured with conditions to only run under certain circumstances using "conditionals". If you've ever dabbled with code you can see this as `if statements`. If you've never dabbled with code you can see this as `if this has happened, do this` .

This conditional setup will only run the module if the user initiating the ticket is me (family friendly)

Most (but not all) modules export `variables` that can be used elsewhere. These variables are accessed by typing `{{variable_name}}`. These variables can be used in these conditional statements, and clicking the blue variable icon to the left of the text box will show you a list of all the variables that are accessible to that specific module.
# Silently Resolve {% hint style="warning" icon="xmark-large" %} **Terminates Pipeline** This module is a pipeline terminator, meaning that no more modules will be ran after this module is ran. {% endhint %} Sometimes you simply want to stop the ticket from being created, instead providing the user a simple message. This can be useful for commonly asked questions and is handled by the `Silently Resolve` module. The module allows you to define a custom embed that will be shown to the user.
# Open Ticket {% hint style="warning" icon="xmark-large" %} **Terminates Pipeline** This module is a pipeline terminator, meaning that no more modules will be ran after this module is ran. {% endhint %} This module creates the actual ticket thread, opening the ticket with the embed you configure within the module. The ticket is created in the `Assigned Channel`
The user is informed of the created threads in a separate message with a button to quickly open the ticket thread directly. If the panel is configured to use AI summaries an extra disclaimer is added to this message to inform the user.
# Assign Channel This module allows you to change the `Assigned Channel` away from that defined on the ticket panel. This allows you to effectively "route" tickets to where they best fit. For example, you may want a ticket about a user report to be routed to a mod channel whereas other tickets are routed elsewhere.
# Assign Name This module is used to set the name of the ticket thread. The text area allows you to use [variables](/features/tickets/templating-language) so you have a lot of flexibility, as long as you follow Discords rules for thread naming.
# Assign Role This allows you to set or add to the `Assigned Roles`. This is effective if you only want certain roles to deal with certain tickets.
# Define Issue This module is arguably one of my favorites! This module will pass the replies to all previous modules to an AI model (`mistral-medium`) and send the user automatic follow-up questions to make sure your mod team has a clear description of the problem without having to ask a lot of follow-ups themselves. You can pick a persona which describes how the AI agent should present itself and rules which the AI will use to know what follow-up questions to ask. You can also configure how many times the AI is allowed to ask follow-up questions before sending the user to the next module in the pipeline. The AI will only ask follow-up questions if it believes the user's inputs have not been enough to follow the rules set by you. If the AI deems the ticket as detailed enough it will pass the user on without asking any questions.
The user is always presented with a "skip" button that will dismiss the AI follow-up process and forcefully move forwards in the pipeline even if the AI did not deem the ticket as detailed enough. This behavior is always on and cannot be altered. # Modal Question This is the bread and butter of your ticket pipeline! It allows you to ask the user directly for inputs.
# Templating Language Hold your horses! It's simple Thread-Watcher's pipeline allows you to "carry" data from one module to the subsequent modules in the pipeline. Any value captured in can be injected into messages, embeds, and even button labels. The ticket panel configuration screen of the website makes finding and inserting these variables a breeze. Simple type `{{` wherever you want to use a variable in a text and a "picker" of different variables will appear on screen where supported! ### The Basics Variables are wrapped in curly braces: `{{variable}}` \ You can access specific properties of a variable by dot notation: `{{variable.property}}`\ For example, to greet a user we can do: ```handlebars Hello there, {{env.user.tag}} ``` ### Lists So far we've looked into "atomic" variables. But, a variable can also be a list of variables. Consider a ticket with a pop-up asking the user to define categories for their ticket. In this case the user might choose multiple available options. Thread-Watcher handles these variables as *lists*. To access a specific variable in a list you use the square brackets and indicate which item you want to select, such as `module.options[2]` to select the third selected option. Thread-Watcher lists are *0 indexed* which means the first item in our list has the index of 0. We can also access lists "backwards" by providing a negative index. \ For example `module.options[-1]` will give us the last item and `module.options[-2]` will give us the second to last answer ### Functions functions will be added at a later time. Thanks for reading :D # Bump Issues Getting annoyed at those pesky messages the bot sends? Let's fix that! {% hint style="warning" %} **Note on Discord limits** Thread-Watcher does not have any limits on the amount of threads you're allowed to watch whatsoever. However, a Discord server can only have a maximum of 1000 threads active at once which might make Thread-Watcher behave strangely if you go above this number. {% endhint %} * Silently editing the thread * Sending a message As you're here you are probably getting tired of Thread-Watcher sending annoying messages in your threads. Don't worry, the fix is just one setting away. {% hint style="info" %} :user-secret: **Private Threads** Private threads work differently than public threads and therefore message bumps are not possible. Please ensure the bot has `Manage Threads` in these channels. {% endhint %} ### Unlocking Silent Bumps for the bot to be able to silently bump threads it needs to be able to edit a thread. For this to be possible you need to ensure that the bot has the `Manage Threads` permission in the channel that holds the thread. ### Audit log is being spammed Thread-Watcher edits threads to bump them, which appends a log into your servers audit log. There's currently no silver bullet to stop this from happening as editing a thread is the only way to silently bump it. You can deny Thread-Watcher the `Manage Threads` permission which will force it to use messages to bump threads. This will stop your audit logs from being spammed, instead spamming the thread with messages. I'm always thinking of ways to achieve completely silent bumps, but so far I've not found a solution. Sorry :c ### Thread is still not being bumped Please ensure that the thread is actually watched. You can list all watched threads with `/list` or on the server web dashboard. If you're not seeing your threads, you need to watch them! If your thread was wrongly configured, meaning Thread-Watcher did not have permissions to bump it thru messages or edits, it might take a while for the bot to start bumping it. Thread-Watcher uses [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) to skip trying to bump threads which have frequently failed being bumped. This is to ensure the bot can operate as smoothly as possible for as many as possible. If you have ensured your permissions are in order and suspect your threads are being affected by this backoff you are welcome to reach out to me in the support server. I'd be glad to remove this flag from your threads so that they work normally again :) # Discord Permissions