> For the complete documentation index, see [llms.txt](https://docs.clashperk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clashperk.com/features/tickets.md).

# Ticket System

Create and manage support or clan application tickets with private channels, staff roles, automated rules, and in-ticket actions.

{% hint style="info" %}
🧪 **Beta** — The Ticket System is available in beta. Some features may still change as we refine it.
{% endhint %}

The Ticket System lets you create **panels** — Discord messages with a button that members click to open a private ticket channel. Each panel supports multiple **application types**, each with its own staff roles, questions, account requirements, and channel settings.

***

## Setting Up a Panel

<mark style="color:blue;">**/ticket setup**</mark> <mark style="color:purple;">**panel\_name:**</mark> `Applications`

If a panel with that name doesn't exist, one is created automatically. A dashboard opens with **Edit** buttons for every section. Click **Done** when finished, or run `/ticket setup` again at any time to reopen it.

Prefer a bigger screen? **Open in dashboard** next to **Done** opens the same panel on the [web dashboard](https://app.clashperk.com) (sign in with Discord).

> You can have multiple panels per server — one for clan applications, one for support, etc.

***

### Step 1 — Embed

The message displayed above the Create Ticket button.

| Field           | Description                                     |
| --------------- | ----------------------------------------------- |
| **Title**       | Bold heading (max 256 chars)                    |
| **Description** | Body text — markdown supported (max 2000 chars) |
| **Color**       | Hex color for the embed border, e.g. `#5865F2`  |

***

### Step 2 — Panel Button

Controls how application types are shown to members.

| Mode                        | Description                                          |
| --------------------------- | ---------------------------------------------------- |
| **Select Menu** *(default)* | One "Create Ticket" button opens a dropdown of types |
| **Buttons**                 | One button per type shown directly — max 5 types     |

In Select Menu mode you can customise the button's label, emoji, and style. In Buttons mode, each type gets its own button configured under Application Types.

***

### Step 3 — Application Types

Each type is a separate option shown when a member clicks the ticket button. If only one type exists, the selection step is skipped.

**To add a type:** click **Edit** → **Add Type**, enter a label and optional emoji (Unicode or custom Discord emoji).

**To edit a type:** click **Edit / Delete** next to it. Each type has its own settings:

#### Staff Roles

| Role type        | What it does                                                                                                |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| **Ping roles**   | Notified when the ticket opens. They get full channel access, including Manage Messages and Manage Channels |
| **Viewer roles** | Can see and send messages in the ticket but cannot manage it                                                |
| **Add roles**    | Added to the ticket creator when the ticket opens, and removed again when it closes                         |
| **Remove roles** | Removed from the ticket creator when the ticket opens, and given back when it closes                        |

#### Apply Rules

Gates checked before the ticket channel is created. **Require linked account** must be enabled for the TH, trophy, and league checks to apply.

| Rule                            | Description                                                                                                      |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Require linked account**      | Member must have a Clash of Clans account linked via `/link create`                                              |
| **TH minimum**                  | Linked account must be at least this Town Hall level                                                             |
| **Min trophies**                | Linked account must have at least this many trophies                                                             |
| **Min league tier**             | Linked account must be in this league or higher                                                                  |
| **Create staff thread**         | Opens a private thread in the ticket for the ping roles. The member who opened the ticket can't see it           |
| **Auto-sleep after inactivity** | Automatically puts the ticket to sleep after N hours with no reply from the creator                              |
| **Allow claiming**              | Staff can claim exclusive ownership — once claimed, all other staff and viewer roles lose access until unclaimed |

#### Questions

Up to **5** questions shown in a pop-up modal before the ticket opens. Each can be marked required or optional.

#### Categories

Discord categories the ticket channel is moved to as its status changes. A closed ticket's channel is deleted, so there's no closed category.

| Category  | When used                                                                    |
| --------- | ---------------------------------------------------------------------------- |
| **Open**  | Channel is placed here when first created, and moves back here when reopened |
| **Sleep** | Channel moves here when put to sleep                                         |

> A Discord category holds at most 50 channels. When the open category is full, new tickets can't be created and the member sees an error.

#### Channel Naming

Controls what the ticket channel is called. Available tokens:

| Token            | Example     | Description                            |
| ---------------- | ----------- | -------------------------------------- |
| `{count}`        | `0042`      | Sequential ticket number (zero-padded) |
| `{user}`         | `johndoe`   | Creator's Discord username             |
| `{account_name}` | `playerone` | Linked Clash of Clans account name     |
| `{account_th}`   | `15`        | Linked account Town Hall level         |

**Default:** `ticket-{count}` → `ticket-0001`

#### Reordering Types

When 2 or more types exist, a **Reorder** button appears. Click it to open a select menu — choose all types in your desired order and submit.

***

### Step 4 — Saved Replies

Pre-written message templates that staff can send inside any ticket with the **Reply** button. Configured at server level and shared across all panels.

Templates support these variables. Any unknown variable prompts a fill-in form when the reply is sent.

| Variable                | Resolves to                                                         |
| ----------------------- | ------------------------------------------------------------------- |
| `{user_mention}`        | Mention of the ticket creator                                       |
| `{user_name}`           | Creator's Discord username                                          |
| `{account_name}`        | Linked Clash of Clans account name                                  |
| `{account_th}`          | Linked account Town Hall level                                      |
| `{account_heroes}`      | Linked account hero levels                                          |
| `{clan_name}`           | Attached clan name                                                  |
| `{clan_tag}`            | Attached clan tag                                                   |
| `{clan_link}`           | Clan profile deep link                                              |
| `{clan_leader}`         | Leader of the attached clan                                         |
| `{clan_leader_mention}` | Mention of the attached clan's leader, if they linked their account |
| `{ticket_count}`        | Ticket number                                                       |
| `{ticket_status}`       | Current ticket status                                               |
| `{server_name}`         | Discord server name                                                 |

When a variable has no value, like `{clan_leader}` on a ticket with no clan set, ClashPerk asks you to fill it in before the reply is sent.

***

### Step 5 — Logging

Send events to specific channels for record-keeping.

| Event             | When it fires                                                               |
| ----------------- | --------------------------------------------------------------------------- |
| **Button click**  | A member clicks the Create Ticket button                                    |
| **Status change** | A ticket is opened, closed, put to sleep, reopened, claimed, or unclaimed   |
| **Ticket close**  | Staff close a ticket (transcript attached, see [Transcripts](#transcripts)) |

#### Transcripts

When a ticket closes, ClashPerk posts its transcript to the **Ticket close** log channel as two files:

* **HTML file:** open it in a browser to read the ticket laid out like the Discord channel.
* **Text file:** easy to search.

The transcript has every message in the ticket, then the private staff thread in its own section. Each message shows who sent it and when, replies and edits, embeds and the names and sizes of attached files. Very long tickets keep their newest 5,000 messages.

Transcripts are only posted to your log channel. ClashPerk doesn't keep a copy. Attached files are listed by name, not saved, so download anything you need before closing.

The ticket header tells members that a transcript is saved. To stop saving transcripts for a panel, turn off **Save transcripts** in the panel's settings on the [web dashboard](https://app.clashperk.com).

{% hint style="info" %}
Members' messages show up in transcripts once Discord approves ClashPerk's access to message content. Until then, transcripts include ClashPerk's own messages and messages that mention ClashPerk.
{% endhint %}

***

### Step 6 — Extra Buttons

Add extra utility buttons to the panel post alongside the Create Ticket button. Members can click these without opening a ticket first.

**Two button types:**

| Type               | How to add                         | Description                              |
| ------------------ | ---------------------------------- | ---------------------------------------- |
| **Command button** | Add Command Button → pick a preset | Dispatches to a bot command when clicked |
| **URL button**     | Add URL Button → enter label + URL | Opens an external link                   |

**Available command button presets:**

| Preset           | What it does                                                                    |
| ---------------- | ------------------------------------------------------------------------------- |
| **Link Account** | Opens the account linking flow so members can link their Clash of Clans account |

**Options per button:** Label, Emoji, Style (Primary / Secondary / Success / Danger — command buttons only). Up to **10 extra buttons** per panel.

**Placement:** Toggle between **Same Row** (extra buttons join the Create Ticket row, spilling to the next row when > 5) and **New Row** (extra buttons always start on a separate row below the Create Ticket button).

> After adding or editing extra buttons, run `/ticket post` again to refresh the live panel message.

***

## Posting a Panel

<mark style="color:blue;">**/ticket post**</mark> <mark style="color:purple;">**panel\_name:**</mark> `Applications`

Run it in the channel where the panel should appear — it posts the panel embed and button there. Run it again any time to refresh the panel message after making changes.

***

## Managing Tickets

Use these commands inside a ticket channel:

| Command                                                     | Description                                                                                          |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">**/ticket sleep**</mark>          | Put the ticket to sleep — restricts creator from sending messages, moves to sleep category           |
| <mark style="color:blue;">**/ticket reopen**</mark>         | Reopen a sleeping ticket — restores creator access, moves back to open category, restarts auto-sleep |
| <mark style="color:blue;">**/ticket close**</mark>          | Close the ticket — posts a transcript to the ticket close log, then deletes the channel              |
| <mark style="color:blue;">**/ticket add**</mark> `[member]` | Add a Discord member to the ticket channel                                                           |

These manage panels and work in any channel:

| Command                                                                                                | Description                                               |
| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| <mark style="color:blue;">**/ticket info**</mark> <mark style="color:purple;">**panel\_name**</mark>   | Show a panel's settings, ticket counts and setup warnings |
| <mark style="color:blue;">**/ticket delete**</mark> <mark style="color:purple;">**panel\_name**</mark> | Delete a panel. Its past tickets stay on the dashboard    |

***

## In-Ticket Buttons

Every ticket channel contains a summary card with action buttons.

| Button            | Who can use it       | What it does                                                                                 |
| ----------------- | -------------------- | -------------------------------------------------------------------------------------------- |
| **Reply**         | Staff                | Send a saved reply template — supports variable fill-in                                      |
| **Set Clan**      | Staff                | Attach a clan to the ticket from the server's configured clans                               |
| **Notify Me**     | Anyone               | Get a DM when the ticket is put to sleep, reopened or closed. Click again to stop            |
| **Claim 🔒**      | Staff *(if enabled)* | Claim exclusive ownership — all other staff and viewer roles lose access                     |
| **Unclaim 🔓**    | Claimer only         | Release the claim and restore all staff access. Reopening a sleeping ticket also releases it |
| **View Account**  | Anyone               | Show linked Clash of Clans account stats                                                     |
| **Delete Ticket** | Staff                | Close the ticket like `/ticket close` (asks for confirmation first)                          |

> The **Claim** button only appears on application types where **Allow claiming** is enabled.

***

## Tickets on the Dashboard

**View tickets** on the Tickets page of the [web dashboard](https://app.clashperk.com) lists every ticket in your server, newest first. Filter by **Open**, **Sleeping** or **Closed**. Each ticket shows who opened it, its panel and type, when it was opened, who claimed it, and links to its channel and staff thread in Discord.

**Close** on an open or sleeping ticket works like the **Delete Ticket** button. ClashPerk posts a [transcript](#transcripts) to the panel's ticket close log, then deletes the channel.

***

## Auto-Sleep

When **Auto-sleep after inactivity** is configured on an application type, the bot automatically puts the ticket to sleep after the set number of hours if the ticket creator hasn't replied. The timer resets each time the creator sends a message. A notification is posted in the ticket channel when it is put to sleep. Reopening the ticket starts the timer again.

***

## Deleted Ticket Channels

If someone deletes a ticket channel in Discord instead of closing it, ClashPerk marks the ticket closed and undoes its role changes. The member can then open a new ticket of that type.

***

## Troubleshooting

#### "Only ticket staff can do this."

The Claim, Unclaim, Reply, Set Clan and Delete buttons work only for ticket staff. You count as staff if you have any of these:

* the **Manage Server** permission
* the [Bot Manager role](https://docs.clashperk.com/others/bot-manager.md)
* the **Manage Channels** permission in the ticket channel. Ping roles get it when the ticket opens.

To let a role handle tickets, add it to the application type's **Ping roles**.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.clashperk.com/features/tickets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
