diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 01a13af..c58ea3b 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -35,7 +35,10 @@ export default defineConfig({ items: [ { text: 'Home', link: '/' }, { text: 'Information', link: '/information' }, - { text: 'FAQ', link: '/faq' } + { text: 'FAQ', link: '/faq' }, + { text: 'Bot Profile', link: '/dashboard/bot-profile' }, + { text: 'Custom Bot', link: '/dashboard/custom-bot' }, + { text: 'My Account', link: '/dashboard/my-account' } ] }, { @@ -49,6 +52,16 @@ export default defineConfig({ { text: 'Pin Leaderboard', link: '/dashboard/pin-leaderboard' }, { text: 'Pin Statistics', link: '/dashboard/pin-statistics' }, { text: 'Giveaways', link: '/dashboard/giveaways' }, + { + text: 'Tickets', + collapsed: false, + items: [ + { text: 'Overview', link: '/dashboard/tickets/index' }, + { text: 'Panel', link: '/dashboard/tickets/panels' }, + { text: 'Templates', link: '/dashboard/tickets/templates' }, + { text: 'History', link: '/dashboard/tickets/history' }, + ] + }, { text: 'Join/Leave Messages', collapsed: false, @@ -59,9 +72,6 @@ export default defineConfig({ { text: 'Welcome Banner', link: '/dashboard/welcome-banner' } ] }, - { text: 'Bot Profile', link: '/dashboard/bot-profile' }, - { text: 'Custom Bot', link: '/dashboard/custom-bot' }, - { text: 'My Account', link: '/dashboard/my-account' } ] }, { @@ -72,7 +82,8 @@ export default defineConfig({ { text: 'Management', link: '/commands/management' }, { text: 'Giveaway', link: '/commands/giveaway' }, { text: 'Verification', link: '/commands/verification' }, - { text: 'Premium', link: '/commands/premium' } + { text: 'Premium', link: '/commands/premium' }, + { text: 'Tickets', link: '/commands/tickets' } ] }, { diff --git a/docs/assets/tickets/automation.png b/docs/assets/tickets/automation.png new file mode 100644 index 0000000..14a4a12 Binary files /dev/null and b/docs/assets/tickets/automation.png differ diff --git a/docs/assets/tickets/claiming.png b/docs/assets/tickets/claiming.png new file mode 100644 index 0000000..799369f Binary files /dev/null and b/docs/assets/tickets/claiming.png differ diff --git a/docs/assets/tickets/escalation.png b/docs/assets/tickets/escalation.png new file mode 100644 index 0000000..db1892b Binary files /dev/null and b/docs/assets/tickets/escalation.png differ diff --git a/docs/assets/tickets/forms.png b/docs/assets/tickets/forms.png new file mode 100644 index 0000000..a6389c6 Binary files /dev/null and b/docs/assets/tickets/forms.png differ diff --git a/docs/assets/tickets/history.png b/docs/assets/tickets/history.png new file mode 100644 index 0000000..4307410 Binary files /dev/null and b/docs/assets/tickets/history.png differ diff --git a/docs/assets/tickets/logging.png b/docs/assets/tickets/logging.png new file mode 100644 index 0000000..a62b689 Binary files /dev/null and b/docs/assets/tickets/logging.png differ diff --git a/docs/assets/tickets/message.png b/docs/assets/tickets/message.png new file mode 100644 index 0000000..7d147c3 Binary files /dev/null and b/docs/assets/tickets/message.png differ diff --git a/docs/assets/tickets/panel.png b/docs/assets/tickets/panel.png new file mode 100644 index 0000000..4fe8270 Binary files /dev/null and b/docs/assets/tickets/panel.png differ diff --git a/docs/assets/tickets/template-binding.png b/docs/assets/tickets/template-binding.png new file mode 100644 index 0000000..29c7327 Binary files /dev/null and b/docs/assets/tickets/template-binding.png differ diff --git a/docs/assets/tickets/template-overview.png b/docs/assets/tickets/template-overview.png new file mode 100644 index 0000000..121d293 Binary files /dev/null and b/docs/assets/tickets/template-overview.png differ diff --git a/docs/assets/tickets/transcripts.png b/docs/assets/tickets/transcripts.png new file mode 100644 index 0000000..187c5e2 Binary files /dev/null and b/docs/assets/tickets/transcripts.png differ diff --git a/docs/commands/tickets.md b/docs/commands/tickets.md new file mode 100644 index 0000000..2d65bd0 --- /dev/null +++ b/docs/commands/tickets.md @@ -0,0 +1,32 @@ +# Tickets Commands + +The explanation for all ticket commands available for Invite Tracker. + +::: info +Ticket commands only work in ticket channels created by the new tickets plugin. +::: + +| Command | Description | +| --- | --- | +| `/ticket-close` | Closes the current ticket channel. | +| `/ticket-rename ` | Renames the current ticket channel. | +| `/ticket-add-user ` | Adds a user to the current ticket channel. | +| `/ticket-remove-user ` | Removes a user's explicit ticket permissions from the current ticket channel. | +| `/ticket-add-role ` | Adds a role to the current ticket channel. | +| `/ticket-remove-role ` | Removes a role's explicit ticket permissions from the current ticket channel. | +| `/ticket-claim` | Claims the current ticket channel. | +| `/ticket-unclaim` | Unclaims the current ticket channel. | +| `/ticket-escalate [reason]` | Escalates the current ticket to an allowed target panel. The target can be the target panel name or ID. | +| `/ticket-automation ` | Starts or stops automations for the current ticket channel. | + +::: info +The **Two Step Close** template setting only applies to the close button. `/ticket-close` closes the ticket immediately. +::: + +::: warning +Support members can manage tickets when they have one of the template's support roles. Administrators can always manage tickets. +::: + +::: warning +Claim, unclaim, escalation, and automation commands require those features to be enabled in the ticket's template. +::: diff --git a/docs/dashboard/tickets/history.md b/docs/dashboard/tickets/history.md new file mode 100644 index 0000000..b01bc0e --- /dev/null +++ b/docs/dashboard/tickets/history.md @@ -0,0 +1,45 @@ +# Ticket History + +The **History** page shows tickets opened in your server. Use it to find open tickets, review closed tickets, and open saved transcripts. + +![Ticket history](/assets/tickets/history.png) + +## Searching Tickets + +You can search by ticket number, channel, member, reason, or Discord ID. + +You can also filter by: + +- Status +- Template +- Panel +- Transcript availability +- Opened date +- Closed date +- Transcript saved date +- Opener ID +- Closer ID + +Dates can be entered as `YYYY-MM-DD` or `DD/MM/YYYY`. + +## History Table + +The history table shows: + +- Ticket ID and channel +- Opener +- Closer +- Template and panel +- Opened and closed dates +- Duration +- Transcript links when a transcript exists + +## Transcripts + +If a ticket has a saved transcript, the History page shows a transcript link. Opening a transcript requires Discord login, and access depends on the template's transcript access settings. + +See [Ticket Templates](/dashboard/tickets/templates#transcripts) for transcript setup. + +::: warning +Deleting a ticket channel manually marks the ticket as closed, but it does not run the normal close flow. Use the close button or `/ticket-close` when you want close roles, close DMs, close logs, and transcripts to run. +::: diff --git a/docs/dashboard/tickets/index.md b/docs/dashboard/tickets/index.md new file mode 100644 index 0000000..cbd0a34 --- /dev/null +++ b/docs/dashboard/tickets/index.md @@ -0,0 +1,47 @@ +# Tickets + +The tickets plugin lets you create support panels that members can use to open private ticket channels. Tickets are configured from the dashboard with **Templates**, **Panels**, and **History**. + +## Before You Start + +Invite Tracker needs permission to create, edit, and delete ticket channels. If you enable role changes, pinned messages, embedded messages, or transcripts, make sure the bot also has permission to manage those roles, pin messages, embed links, and read message history. + +::: warning +If Invite Tracker cannot create or delete channels, update channel permissions, or send messages in the configured channels, tickets may fail to open, close, claim, escalate, or save transcripts. + +Please ensure that the bot has the correct [permissions](/faq#what-are-the-required-permissions-for-invite-tracker). +::: + +## How Tickets Work + +A ticket setup has two main parts: + +1. **Templates** define what happens when a ticket opens. This includes the ticket category, channel name, support roles, messages, forms, transcripts, claiming, escalation, logs, and automations. +2. **Panels** are the messages members click in Discord. A panel can show ticket buttons or one select menu, and each panel option is connected to a template. + +After members start opening tickets, the **History** page gives you a searchable list of open and closed tickets. + +![Tickets overview](/assets/tickets/panel.png) + +## Setup Order + +To set up tickets, use the dashboard pages in this order: + +1. Create at least one [ticket template](/dashboard/tickets/templates). +2. Create a [ticket panel](/dashboard/tickets/panels) and bind templates to it. +3. Save the panel, then click **Send Panel** to post it in Discord. +4. Use [Ticket History](/dashboard/tickets/history) to review open and closed tickets. + +## What Members See + +Members open a ticket by clicking a panel button or choosing an option from a panel select menu. If the selected template has a form, Invite Tracker opens a Discord modal first. After the form is submitted, Invite Tracker creates a private ticket channel for the member and support roles. + +## Ticket Commands + +Ticket commands work inside open ticket channels. They are mostly used by support members with the template's support roles, while administrators can always manage tickets. Ticket owners can also close their own ticket when **Opener Can Close** is enabled. + +For the full command list, see [Tickets Commands](/commands/tickets). + +::: warning +Deleting a ticket channel manually marks the ticket as closed, but it does not run the normal close flow. Use the close button or `/ticket-close` when you want close roles, close DMs, close logs, and transcripts to run. +::: diff --git a/docs/dashboard/tickets/panels.md b/docs/dashboard/tickets/panels.md new file mode 100644 index 0000000..b97b045 --- /dev/null +++ b/docs/dashboard/tickets/panels.md @@ -0,0 +1,65 @@ +# Ticket Panels + +Ticket panels are the Discord messages members use to open tickets. Create panels from your server's dashboard by opening **Tickets** -> **Panels**. + +Before creating a panel, create at least one [ticket template](/dashboard/tickets/templates). + +![Ticket panel](/assets/tickets/panel.png) + +## Creating a Panel + +Click **Create Panel** to create a new panel. A panel must be saved before it can be sent to Discord. + +## Panel Management + +The **Panel Management** section controls where the panel message is sent and how members choose a ticket type. + +- **Panel Name** is the internal dashboard name. +- **Panel Channel** is where **Send Panel** posts the panel message. +- **Component Type** can be **Buttons** or **Select**. +- **Ticket Count** is the current counter used by ticket naming. +- **Select Placeholder** is the placeholder text shown when using a select menu. + +Click **Save** before sending a panel. After the panel is saved, click **Send Panel** to post it in Discord. If you change the panel later, click **Edit Sent Panel** to update the existing Discord message. + +## Panel Limits + +Panel limits control how many open tickets can exist from the panel. + +- **Open Limit Per User** limits how many open tickets one member can have from this panel. +- **Open Limit All Users** limits how many open tickets the whole server can have from this panel. +- **Limit Bypass Roles** allows selected roles to ignore panel and template ticket limits. + +Set a panel limit to `0` to disable that limit. + +## Template Bindings + +Template bindings decide which ticket options appear on the panel. + +Each binding connects one template to one panel option. The binding label is what members see on the button or select menu option. You can also configure a description, emoji, and button style. + +![Ticket panel bindings](/assets/tickets/template-binding.png) + +::: warning +A panel must have at least one template binding, and each template can only be bound once per panel. +::: + +## Panel Message + +The **Panel Message** section controls the message Invite Tracker sends for the panel. You can use plain text or an embed. + +Supported panel variables include `{panel.name}`, `{schedule.timezone}`, `{bot.avatar}`, and `{specialchars}`. + +## Schedule + +Panel schedules let you control when regular members can open tickets from a panel. + +When scheduling is enabled, choose a timezone and add opening-hour entries. Each entry has a day, start time, and end time. If the start time is later than the end time, the schedule continues past midnight into the next day. + +Use **Schedule Bypass Roles** for staff or trusted roles that should still be able to open tickets outside the schedule. + +::: info +If scheduling is enabled and no schedule entries are configured, the panel is treated as closed. + +If a schedule entry has the same start and end time, that day is treated as open for the full day. +::: diff --git a/docs/dashboard/tickets/templates.md b/docs/dashboard/tickets/templates.md new file mode 100644 index 0000000..50626ff --- /dev/null +++ b/docs/dashboard/tickets/templates.md @@ -0,0 +1,197 @@ +# Ticket Templates + +Ticket templates define how new tickets are created and managed. Create templates from your server's dashboard by opening **Tickets** -> **Templates**. + +![Ticket template](/assets/tickets/template-overview.png) + +## Creating a Template + +To create your first template, click **Create your first template**. If you already have a template, click **New Template**. + +Each template has tabs for identity, messages, roles, transcripts, claiming, escalation, forms, automations, logs, and buttons. + +## Identity + +The **Identity** tab controls the core ticket behavior. + +- **Template Name** is the internal name shown when binding the template to a panel. +- **Ticket Category** is where new ticket channels are created. +- **Overflow Categories** are fallback categories used when the main category is full. +- **Naming Pattern** controls the ticket channel name. Supported tokens are `{counter}`, `{counter:04}`, `{username}`, `{user_id}`, and `{template}`. +- **Support Roles** are the roles that can see, write in, and manage tickets created from this template. +- **Two Step Close** asks users to confirm before a close button closes the ticket. +- **Pin Initial Message** pins the first Invite Tracker message inside the ticket channel. +- **Tickets Per User** limits how many open tickets each member can have from this template. +- **Opener Can Close** controls whether the member who opened the ticket can close it. + +::: tip +Use a padded counter such as `ticket-{counter:04}` if you want ticket channels like `ticket-0001`, `ticket-0002`, and `ticket-0003`. +::: + +::: warning +Discord categories can only contain 50 channels. If the main ticket category is full, Invite Tracker tries the configured overflow categories in order. If no configured category is available, opening, claiming, or escalating a ticket may fail until you free space or add another overflow category. +::: + +## Messages + +The **Messages** tab controls the first message sent inside a new ticket and the optional direct message sent when the ticket closes. + +The **Initial Message** is posted in the ticket channel as soon as it opens. You can use plain text or a rich embed, and you can include ticket variables such as the ticket owner, channel, panel, template, and form answers. + +The **Close DM** is sent to the ticket owner when the ticket closes. If transcripts are enabled, you can also attach an **Open transcript** button to this DM. + +![Ticket messages](/assets/tickets/message.png) + +::: warning +The close DM transcript button requires **Ticket Owner Access** to be enabled in the Transcripts tab. +::: + +::: info +The **Two Step Close** setting only applies to the close button. The `/ticket-close` command closes the ticket immediately. +::: + +## Role Changes + +The **Roles** tab lets you automatically add or remove roles from the ticket owner. + +- **Add On Open** and **Remove On Open** run when the ticket is created. +- **Add On Close** and **Remove On Close** run when the ticket closes. + +This is useful when you want to mark members as waiting for support, remove a role while a ticket is open, or grant a role after a support flow finishes. + +::: warning +Invite Tracker can only add and remove roles that are below its highest role in your server's role list. +::: + +## Transcripts + +The **Transcripts** tab controls whether Invite Tracker saves an HTML transcript when a ticket closes. + +When transcripts are enabled, Invite Tracker saves the ticket messages and form answers when the ticket closes. You can choose an optional **Transcript Channel** where Invite Tracker sends a ticket summary and an **Open transcript** button. + +![Ticket transcripts](/assets/tickets/transcripts.png) + +Transcript access is controlled by the template: + +- **Support Access** allows members with the template's support roles to open the transcript. +- **Ticket Owner Access** allows the member who opened the ticket to open the transcript. +- Server administrators can access ticket transcripts. + +::: info +Transcript links require users to sign in with Discord. A user can only open the transcript if their Discord account is allowed by the template access settings. +::: + +::: info +Transcripts include up to the most recent 5000 ticket messages. Very large transcripts may be shortened so they can be stored and opened reliably. +::: + +::: warning +At least one transcript access option must stay enabled. If you want to send transcript buttons in close DMs, keep **Ticket Owner Access** enabled. +::: + +## Claiming + +The **Claiming** tab lets support members take responsibility for a ticket. + +When claiming is enabled, support members can use the claim button or `/ticket-claim` in the ticket channel. Claiming can rename the channel, move it to a claim category, adjust support permissions, and change roles on the ticket owner. + +![Ticket claiming](/assets/tickets/claiming.png) + +Important claiming settings: + +- **Only Claimer Can Unclaim** restricts unclaiming to the current claimer, except for administrators. +- **Limit Claimed Actions** allows only the claimer and ticket owner to use ticket actions while the ticket is claimed. +- **Overwrite Claimer** lets another support member replace the current claimer. +- **Owner Can Claim** allows the ticket owner to claim the ticket when support permissions are not changed. +- **Support Permission Mode** decides what happens to other support roles after a claim. They can stay unchanged, become read-only, or be hidden from the ticket. +- **Claim Name** renames the ticket while claimed, then restores the original opened name when unclaimed. +- **Claim Category** and **Claim Overflow Categories** move claimed tickets into another category. +- **Add/Remove On Claim** and **Add/Remove On Unclaim** change roles on the ticket owner. + +## Escalation + +Escalation lets support members move an open ticket to another panel's first template by using `/ticket-escalate`. + +First, enable escalation on the source template and select the **Target Panels** that tickets are allowed to escalate into. When a ticket is escalated, Invite Tracker can update the category, channel name, permissions, claim state, and messages using the target panel's first active template. + +![Ticket escalation](/assets/tickets/escalation.png) + +You can choose whether escalation should: + +- Move the channel into the target template's category. +- Rename the channel using the target template's naming pattern. +- Replace support permissions with the target template's support roles. +- Automatically unclaim the ticket during transfer. +- Send a short escalation message. +- Send the target template's full initial ticket message. + +::: tip +Use escalation when your first support team needs to hand a ticket to another team, such as billing, appeals, partnerships, or senior moderators. +::: + +## Forms + +The **Forms** tab lets you ask members questions before their ticket is created. + +When forms are enabled, clicking the ticket panel opens a Discord modal. You can add up to 5 questions, choose short or paragraph answers, set whether each answer is required, and configure minimum and maximum answer lengths. + +![Ticket form](/assets/tickets/forms.png) + +You can show form answers in ticket messages using form variables. This lets support members see the member's issue immediately in the first ticket message. + +::: warning +Form titles and question labels can be up to 45 characters. Question placeholders can be up to 100 characters, and answer limits can go up to 4000 characters. +::: + +## Automations + +The **Automations** tab lets Invite Tracker react to ticket events after a delay. + +Automation triggers include: + +- **Ticket Created** +- **Ticket Owner Left Server** +- **Message Found** +- **Message Not Found** + +Automation actions include: + +- **Send Message** +- **Close Ticket** + +For message-based automations, you can choose whether Invite Tracker checks messages from anyone, only the ticket owner, or only the support team. You can also choose whether the automation checks once or keeps checking until it is stopped. + +![Ticket automations](/assets/tickets/automation.png) + +::: warning +Ticket automations can have up to 10 rules per template. Message-based automations must wait at least 5 minutes, and any automation delay can be up to 7 days. +::: + +::: tip +Support members can use `/ticket-automation stop` in an open ticket to pause automations for that ticket, and `/ticket-automation start` to start them again. +::: + +## Logs + +The **Logs** tab lets you send ticket lifecycle logs to a text channel. + +You can log: + +- Ticket created +- Ticket closed +- Transcript saved +- Ticket claimed +- Ticket unclaimed +- Ticket escalated + +![Ticket logs](/assets/tickets/logging.png) + +## Buttons + +The **Buttons** tab lets you configure the ticket action buttons shown on the first ticket message. + +You can enable or disable the **Close**, **Claim**, and **Unclaim** buttons, set their emoji, change their label, and choose their Discord button style. + +::: info +Claim and unclaim buttons only appear when claiming is enabled for the template. +::: diff --git a/docs/faq.md b/docs/faq.md index d94d597..8649c23 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -18,7 +18,9 @@ Lastly, if Invite Tracker is not responding to a mention, please make sure Invit ## How do I set up invite roles? -This feature has sadly been disabled due to it being against Discord's Developer Terms of Service. Having any features that include rewarding invites just enables server advertisement in servers and direct messages. This is something Discord views as unsolicited advertisement, which is exactly what breaks the Discord Developer Policy. +This feature has been disabled due to it being against Discord's Developer Terms of Service. Having any features that include rewarding invites just enables server advertisement in servers and direct messages. This is something Discord views as unsolicited advertisement, which is exactly what breaks the Discord Developer Policy. + +You can view this policy [here](https://discord.com/safety/platform-manipulation-policy-explainer) ::: info Invite requirements for giveaways is also disabled due to being against Discord's Developer Terms of Service for the same reason as invite roles. @@ -62,16 +64,16 @@ If you want to give Invite Tracker all permissions without any more hassle, you | --- | --- | | `Administrator` | Grants all permissions | | `Manage Server` | Needed to view the server's active invites so it can track them | -| `Manage Roles` | Needed to grant roles such as reward roles, auto roles, winner roles, and verification roles | -| `Manage Channels` | Needed for the bot to be able see invites created in a channel for tracking invites | +| `Manage Roles` | Needed to manage tickets and grant roles such as reward roles, auto roles, winner roles, and verification roles | +| `Manage Channels` | Needed to manage tickets and grant roles such as reward roles, auto roles, winner roles, and verification roles | | `Kick Members` | Needed to kick members for verification action | | `Ban Members` | Needed to ban members for verification action or for mass bans | | `View Channel` | Needed to view messages so it can either respond to or track them | | `Send Messages` | Needed to respond to commands, edit messages, and send join/leave/test messages | -| `Pin Messages` | Needed to pin leaderboards | +| `Pin Messages` | Needed to pin leaderboards and pin ticket messages | | `Embed Links` | Needed to send embeds such as leaderboards, embedded join/leave messages, and giveaways | | `Attach Files` | Needed to send statistical graphs and exports of the leaderboard | -| `Read Message History` | Needed to view older messages so it may edit them such as pinned leaderboards and giveaways | +| `Read Message History` | Needed to view older messages to edit them (such as pinned leaderboards and giveaways) and to save ticket transcripts | | `Add Reactions` | Needed to react to join/leave messages | | `Use External Emojis` | Needed to use server emojis in your join/leave messages |