# Welcome!

Official documentation for ClashPerk, a Discord bot for Clash of Clans clan management.

ClashPerk is a powerful Discord bot designed for Clash of Clans. With its wide array of features and intuitive interface, ClashPerk brings convenience, efficiency, and enhanced coordination to your clan management.

Easy to set up and highly customizable, ClashPerk works with simple slash commands.

## Quick Links

{% content-ref url="/pages/i5Qi4JHHOyOmd2asnVhI" %}
[Getting set up](/overview/getting-set-up)
{% endcontent-ref %}

{% content-ref url="/pages/vHgZ8v0R8GzxJC8Hv3V5" %}
[Link account](/overview/link-account)
{% endcontent-ref %}

{% content-ref url="/pages/ZF8XE0SXwfdUpwdgGAOU" %}
[Bot Personalizer](/features/bot-personalizer)
{% endcontent-ref %}

{% content-ref url="/pages/lBntq1Y6kMzCQCGpi5n4" %}
[Rosters](/features/rosters)
{% endcontent-ref %}


# FAQ

Frequently Asked Questions

## Is ClashPerk Legal / Fair Play?

Yes, we always support Fair Play. ClashPerk collects all data directly from the official Supercell API.

## Why is the bot not working on my server?

Make sure that ClashPerk has all the required permissions in your Discord. Run the <mark style="color:blue;">**/debug**</mark> command to check missing permissions and other issues.

## What is clan verification?

To prevent abuse, the bot verifies that you're a leader or co-leader of the clan. This ensures you're not tracking clans you don't own or adding the same clan to multiple servers.

## How does last seen work?

Due to API limitations, the bot can't directly see who is online or recently active. Instead, we estimate a player's last-seen time based on the following activities. These give us a rough idea of when someone was last active in the clan.

* [x] Player name changed
* [x] Troops donated
* [x] Trophies gained in the Legend league
* [x] Versus trophies gained
* [x] Switch clans (leave the current clan and join another)
* [x] Multiplayer attacks won
* [x] War preference changed
* [x] Clan capital gold contributed or looted
* [x] Clan games points scored
* [x] Obstacle removed
* [x] Resources (gold/elixir/dark) looted
* [x] Super Troops boosted
* [x] Goblin stars earned
* [x] Attacked in war (CWL/Regular/Friendly)
* [x] Artilleries, Monolith, Walls, Builder huts, Inferno towers, Mortars, Xbows, Spell towers, and Scattershots destroyed

## What is activity score?

Whenever the bot captures an activity (mentioned above), the player gets a +1 score. This score reflects the total number of activities the bot has seen for that player, helping us determine who the most active or inactive members are.

## How does the clan games scoreboard work?

Clan Games points can't be directly pulled from the API. Instead, we track the **Games Champion** achievement. At the start of Clan Games, we capture each player's progress and then compare it every 10-15 minutes. The difference shows how many points they've earned during the event, and this updates the scoreboard.

## Why is Gold/Elixir looted 0 for some players?

Once a player hits 2 billion in looted Gold or Elixir, the API stops increasing the count. This is an API limitation that affects players who reach this cap.

## Is my API token safe to share?

Yes, your API token cannot be used to steal your account or gain access to any account-related data. It only verifies your identity with third-party services. The token resets periodically and becomes invalid after each use.

## How does ClashPerk track game data?

ClashPerk tracks game data using the official Clash of Clans API, which does not provide real-time events. The only way to observe changes is by polling the API at safe intervals.

Polling simply means checking the API from time to time to see what the current data looks like, instead of being notified instantly when something changes.

### Why this can’t be real-time

* The official API has rate limits and no push/webhook system, so continuous tracking isn’t possible.
* ClashPerk tracks a large number of clans and players, and completing a full polling cycle takes time.
* Some in-game updates take time to appear in the API itself.

### Examples

* Trophy changes: A player gains trophies from an attack and loses them in a defense before the next poll. Only the final value is visible, so the intermediate change isn’t recorded.
* War attacks: A war attack happens shortly after a poll and only appears on the next API check, making it seem delayed.
* Clan join/leave: A player leaves a clan and rejoins before the next poll. Since the state briefly changed and reverted, ClashPerk may never observe the leave.

These limitations apply to almost all tracked data. ClashPerk records snapshots based on what the API exposes, so short delays or missed short-lived changes are unavoidable.


# Getting set up

Get started with the ClashPerk bot.

#### Invite the bot to your server (do this first)

<details>

<summary>Add ClashPerk</summary>

Before you can run any command, ClashPerk needs to be in your server. Head to [clashperk.com](https://clashperk.com) and use the **Add to Discord / Invite** link, then pick your server and approve the requested permissions.

{% hint style="info" %}
Already have ClashPerk in another server? You can also run <mark style="color:blue;">**/invite**</mark> from any server where the bot is present to get the invite link.
{% endhint %}

</details>

#### Link a clan to your Discord Server (required)

<details>

<summary>Link to Server</summary>

The following command allows you to quickly add your clan to the server, enabling the bot to track it.

<mark style="color:blue;">**/setup clan**</mark> <mark style="color:purple;">**clan:**</mark> `#CLAN_TAG`

</details>

#### Set a default clan for a channel (optional)

<details>

<summary>Link to Channel</summary>

Allows you to link a clan to a channel. (one clan per channel)

<mark style="color:blue;">**/setup clan**</mark> <mark style="color:purple;">**clan:**</mark> `#CLAN_TAG` <mark style="color:purple;">**clan\_channel:**</mark> `#general`

* [x] This link enables you to run commands without entering or selecting a clan tag.
* [x] You can repeat the process to link the clan in multiple channels.

</details>

#### Create a Clan Embed (optional)

<details>

<summary>Clan Embed</summary>

Clan embed is for showcasing your clans in a public channel.

<mark style="color:blue;">**/setup clan-embed**</mark> <mark style="color:purple;">**clan:**</mark> `#CLAN_TAG`

</details>

#### Enable Logs (optional)

**Initiate Setup**

If you don't select a channel, it defaults to the current channel.

<mark style="color:blue;">**/setup clan-logs**</mark> <mark style="color:purple;">**clan:**</mark> `#CLAN_TAG` <mark style="color:purple;">**channel:**</mark> `#channel`

Clan Logs:

* Clan Achievements Log
* Donation Log (Instant/Daily/Weekly/Monthly)
* Clan Games Embed Log
* Last Seen Embed Log
* Legend Attacks Daily Summary Log

Capital Logs:

* Clan Capital Weekly Summary Log
* Capital Gold Contribution Log
* Capital Gold Raid Log

War Logs:

* War Attack Log
* CWL Attack Log
* War Embed Log
* War Missed Attacks Log
* CWL Embed Log
* CWL Missed Attacks Log
* CWL Lineup Change Log
* CWL Monthly Summary Log

Player Logs:

* Member Join/Leave Log
* Role Change Log
* Name Change Log
* Town Hall Upgrade Log
* War Preference Log
* Ranked Battle League Change Log

{% hint style="info" %}
For more information, see [Logs](/features/logs)
{% endhint %}

**Disable a Log**

<mark style="color:blue;">**/setup clan-logs**</mark> <mark style="color:purple;">**action:**</mark> `Disable` <mark style="color:purple;">**clan:**</mark> `#CLAN_TAG`


# Link account

Link and verify accounts!

## Link yourself!

Why bother entering your clan/player tag again and again? Link your accounts and use commands without entering the clan/player tag.

{% tabs %}
{% tab title="LINK PLAYER" %}
You can link up to 25 villages to your Discord user account.

<mark style="color:blue;">**/link create**</mark> <mark style="color:purple;">**player\_tag:**</mark> `#PLAYER_TAG`

**Link on behalf of someone**

<mark style="color:blue;">**/link create**</mark> <mark style="color:purple;">**player\_tag:**</mark> `#PLAYER_TAG` <mark style="color:purple;">**user:**</mark> `@user-mention`
{% endtab %}

{% tab title="LINK CLAN" %}
You can link one clan to your Discord user account.

<mark style="color:blue;">**/link create**</mark> <mark style="color:purple;">**clan\_tag:**</mark> `#CLAN_TAG`
{% endtab %}
{% endtabs %}

## Verify account

You need the API token from the in-game settings to verify an account.

{% tabs %}
{% tab title="VERIFY AND LINK" %} <mark style="color:blue;">**/verify**</mark> <mark style="color:purple;">**player:**</mark> `#PLAYER_TAG` <mark style="color:purple;">**token:**</mark> `API_TOKEN`
{% endtab %}
{% endtabs %}

### Is my API token safe to share?

Yes, your API token cannot be used to steal your account or gain access to any account-related data. It only verifies your identity with third-party services. The token resets periodically and becomes invalid after each use.

### How do you get your API token?

1. Open Clash of Clans and navigate to **Settings > More Settings**
2. Scroll down to the bottom and click on **`Show`** next to the **API Token**
3. Click **`Copy`** to copy your API token


# Rosters

The roster management feature provides a comprehensive solution for efficient and organized management of CWL/War events.

Rosters are designed to streamline CWL/War signups and prevent duplicate registrations. It offers convenient features such as autocomplete to easily add individual players from your clan family, and the ability to add players in bulk while detecting player tags regardless of their format.

The feature allows you to set the start and end times for the roster and provides a roster settings button for easy management. You can open or close the roster, hide or show signup buttons, enable archive mode, add or remove players, move players, change groups, edit settings and layout, export members, and clear the roster.

User groups can be created for managing roles, and a wide range of restrictions can be set, including the ability for members to select a group, sign up for multiple rosters, or meet specific criteria such as minimum/maximum town hall level or combined hero levels.

The feature also allows for keeping a history of the rosters by closing them instead of deleting or clearing them every month.

## Quick start CWL Roster

To create a roster for CWL, use the following command:

<mark style="color:blue;">**/roster create**</mark> <mark style="color:purple;">**clan:**</mark>`clan`<mark style="color:purple;">**name:**</mark>`CWL`<mark style="color:purple;">**allow\_multi\_signup:**</mark>`False`<mark style="color:purple;">**category:**</mark>`CWL`

This will generate an Embed which can be posted using:

<mark style="color:blue;">**/roster post**</mark> <mark style="color:purple;">**roster:**</mark>`CWL`

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2F3t1UppCgvM6imW0D76H6%2FScreenshot%202024-07-23%20230118.png?alt=media&amp;token=fcd52c41-d029-4719-b408-fd770c3e835e" alt=""><figcaption><p>Roster Embed</p></figcaption></figure>

When you decide to close the sign-up period, it is preferred to hide the buttons via the :gear:[Button](/features/rosters/button).

#### Signing up

Pressing the <mark style="color:green;">Signup</mark> allows a Player to signup. They need to select the Accounts they want to signup. They also may choose a Group. The default Groups are <mark style="color:purple;">Confirmed</mark> and <mark style="color:purple;">Substitute</mark>. If none are selected it will default to the first Group.

#### Opting out

If a Player wishes to opt out after signing up, they can press the <mark style="color:red;">Opt-out</mark> button. They will then be prompted to select the Accounts they want to opt-out.

#### Managing the roster

The user that has the Manager Roster role can use the :gear:[Button](/features/rosters/button) to manage it.

#### Editing the roster

With <mark style="color:purple;">/roster edit</mark> all options can be edited. :pencil2:[Create, Edit, Delete and Clone Rosters](/features/rosters/create-edit-delete-and-clone-rosters)

#### Refresh Button

Refresh the Roster immediately and apply any changes. Sometimes it takes a little bit for the roster to update.


# Create, Edit, Delete and Clone Rosters

detailed explanation of the /roster create, /roster edit, /roster delete and /roster clone

## Creating a Roster

<mark style="color:blue;">**/roster create**</mark> `[clan] [name] [...options]`

### Roster options

* **Category** - Choose between CWL, WAR, ESPORTS and TROPHY. CWL shows league as well. TROPHY shows the amount of trophies in the roster.
* **import\_members** - Whether to import members from the clan (<mark style="color:blue;">default</mark>: False)
* **allow\_unlinked** - Whether to allow unlinked members (<mark style="color:blue;">default</mark>: False)
* **max\_members** - Roster size (<mark style="color:blue;">default</mark>: 65)
* **max\_accounts\_per\_user** - How many accounts per user should be allowed (default: unlimited)
* **min\_town\_hall** - Minimum Town Hall level needed to sign up (<mark style="color:blue;">default</mark>: TH 2)
* **max\_town\_hall** - Maximum Town Hall level (<mark style="color:blue;">default</mark>: the current max Town Hall level, TH 18)
* **min\_hero\_level** - Minimum combined Hero level need to sign up (<mark style="color:blue;">default</mark>: 0)
* **roster\_role** - The role the players get when they sign up
* **sort\_by** - Sort by Player Name, Discord Name, Discord Username, Town Hall Level, Hero Levels, TH + Hero Levels, Clan Name, Signup Time, Trophies, Leagues (<mark style="color:blue;">default</mark>: SIGNUP\_TIME)
* **start\_time** - The start time of sign-up. Format: YYYY-MM-DD HH:mm (24 Hours) (<mark style="color:blue;">default</mark>: N/A)
* **end\_time** - The end time of sign-up. Format: YYYY-MM-DD HH:mm (24 Hours) (<mark style="color:blue;">default</mark>: N/A)
* **timezone** - Search timezone by city or country (e.g. London, Singapore, Germany, Stuttgart) (<mark style="color:blue;">default</mark>: UTC)
* **allow\_group\_selection** - Whether to allow members to select a <mark style="color:purple;">Public</mark> group (<mark style="color:blue;">default</mark>: True)
* **allow\_multi\_signup** - Whether to allow a user to sign up for multiple rosters in the same category (<mark style="color:blue;">default</mark>: True)
* **use\_clan\_alias** - Whether to use clan alias in the roster (created by /alias command) (<mark style="color:blue;">default</mark>: False)
* **color\_code** - Hex color code of the roster embed
* **roster\_image\_url** - Image URL to display in the roster embed

{% hint style="info" %}
When setting a Timezone ClashPerk will remember that Timezone for you! (It links the Timezone to your account)
{% endhint %}

## Editing a Roster

<mark style="color:blue;">**/roster edit**</mark>`[roster] [...options]`

* **clan** - change which clan it is connected to
* **name** - change the name of the roster
* **delete\_role** - delete the roster using True
* ... see the options at <mark style="color:purple;">**/roster create**</mark>

## Deleting a Roster

<mark style="color:blue;">**/roster delete**</mark>`[roster]`

{% hint style="danger" %}
Completely deletes the roster.
{% endhint %}

## Cloning a Roster

<mark style="color:blue;">**/roster clone**</mark> <mark style="color:purple;">**roster:**</mark>`Roster`<mark style="color:purple;">**name:**</mark>`Name`

Clones the Roster settings to a new Roster without importing the Members from the Source Roster.


# Button

Manage roster buttons and actions visually.

The following options are available:

<details>

<summary>Roster Info/Export</summary>

View roster info and settings, or export the roster.

See [Exporting Rosters](/features/rosters/exporting-rosters) for more information!

</details>

<details>

<summary>Close Roster</summary>

It is like a soft delete. <mark style="color:red;">Recommended</mark> to use Hide Buttons to prevent signups etc.

You need to reopen the Roster to make any further changes.

<mark style="color:orange;">Note</mark>: This roster will be excluded from the multi\_sign\_up setting

</details>

<details>

<summary>Clear Roster</summary>

Removes all members from the roster at once, leaving the roster itself intact.

</details>

<details>

<summary>Hide Buttons</summary>

Hide the <mark style="color:green;">signup</mark> and <mark style="color:red;">opt-out</mark> buttons from the message.

</details>

<details>

<summary>Archive Mode</summary>

Remove action buttons from the message. The Embed will become unchangeable.

</details>

<details>

<summary>Manage Roster on the Web</summary>

Opens a link to manage this roster from the ClashPerk web dashboard.

</details>

<details>

<summary>Add User</summary>

Add a user or player to the roster.

<img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2FKdnCDKXkpsyTZPRqpzqg%2Fimage.png?alt=media&amp;token=34c1163d-be94-4d17-bc6f-fe35cd121da0" alt="" data-size="original">

* You can select an account to add all connected accounts or select which accounts to add
* <mark style="color:purple;">Bulk Add</mark> takes in any form of in-game IDs to bulk add those accounts to the roster
* With <mark style="color:red;">Deselect</mark> you can remove accounts from the selection

To apply the changes press <mark style="color:blue;">Confirm</mark>

</details>

<details>

<summary>Remove User</summary>

Remove a user or players from the roster.

<img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fvkhbquvl8woz9zSQuDBy%2FScreenshot%202024-07-24%20000329.png?alt=media&amp;token=3c0a2f9a-227d-4f6b-ac35-fe50fed6c24c" alt="" data-size="original">

Works similarly to Add User.

</details>

<details>

<summary>Change Roster</summary>

Move a user or players to another roster.

<img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2FZ8U3N73hS3IL39GgKwIl%2FScreenshot%202024-07-24%20000839.png?alt=media&amp;token=977fb0e0-7801-4a0c-bc70-fe1f98cbbd08" alt="" data-size="original">

</details>

<details>

<summary>Change Group</summary>

Move a user or players to another group within the roster.

</details>

<details>

<summary>Edit Roster</summary>

Edit roster layout and sorting options.

**Custom Layout using&#x20;**<mark style="color:purple;">**3 to 5**</mark>**&#x20;of the following options:**

* **Index** - The index of the player in the roster.
* **Town Hall Level** - The Town Hall level of the player.
* **Town Hall Icon** - The Town Hall icon of the player.
* **Discord Name** - The Discord display-name of the player.
* **Discord Username** - The Discord username of the player.
* **Discord User ID** - The Discord User ID of the player.
* **Player Name** - The name of the player.
* **Player Tag** - The tag of the player.
* **Clan Name / Alias** - The clan name of the player.
* **Combined Hero Level** - The combined hero level of the player.
* **Role** - The role of the player in the clan.
* **War Preference** - The war preference of the player in the clan.
* **Trophies** - The trophies of the player.
* **League Icon** - The league icon of the player.

**Sort the roster by&#x20;**<mark style="color:purple;">**one**</mark>**&#x20;of the following options:**

* Player Name
* Discord Name
* Discord Username
* Town Hall Level
* Hero Levels
* TH + Hero Levels
* Clan Name
* Signup Time
* Trophies
* Leagues

</details>

<details>

<summary>Unregistered Members</summary>

List of members who did not sign up for the roster.

* Name and ID of the player

</details>

<details>

<summary>Missing Members</summary>

List of roster members who are currently not in the clan.

* Name and ID of the player

</details>

{% hint style="info" %}
Using <mark style="color:blue;">**/roster manage**</mark> you can do the following options too!

* Add User
* Remove User
* Change Roster
* Change Group
  {% endhint %}


# Roster Ping

Ping members in the roster

<mark style="color:blue;">**/roster ping**</mark> <mark style="color:purple;">**message:**</mark>`Message`<mark style="color:purple;">**ping\_option:**</mark>`Option`<mark style="color:purple;">**group:**</mark>`Group`

### Message

Type here the message that should be displayed.

### Option

Choose between:

* Unregistered (didn't sign up, but in the clan)
* Missing (opted-in, but not in the clan)
* Everyone (all opted-in members)

{% hint style="warning" %}
After submitting the Command it will ask to Confirm before pinging!
{% endhint %}

### Group

Restrict the pings to a certain Group. Leave empty to ignore.


# List Rosters and Groups

A detailed explanation of how to list rosters and groups

<mark style="color:blue;">**/roster list**</mark> <mark style="color:purple;">**name:**</mark> `Name` <mark style="color:purple;">**user:**</mark> `User` <mark style="color:purple;">**player\_tag:**</mark> `Tag` <mark style="color:purple;">**clan:**</mark> `Clan`

### Getting all Rosters and Groups

Run the <mark style="color:blue;">**/roster list**</mark>

Shows Rosters with Index, Name, Clan and amount of Members/Max Members.

Shows Groups with Index, Name, (Public/Private) Status and \[Order X]

{% hint style="warning" %}
Groups are only shown when running the command without filter options.
{% endhint %}

### Options / Filter

Filter **Rosters** using any of the following Options:

* **name** - List any Roster with the set Name
* **user** - List any Roster where that user is in with an Account
* **player\_tag** - List all Rosters where that Account is in
* **clan** - List all Rosters from that specific Clan


# Managing Groups

A detailed explanation of how to manage Groups. Players will be able to sign up with a group. This is used to separate players into different groups in a roster. For example Confirmed and Substitute.

## Default Groups

* **Confirmed** - The player that is confirmed to play
* **Substitute** - Player that may be substituted

## Creating a Group

<mark style="color:blue;">**/roster groups create**</mark> <mark style="color:purple;">**name:**</mark> `Name [...Options]`

* **name** - Set the Name of the Group
* **group\_role** - Give the Group a Role.
* **selectable** - Whether to allow Members to select this Group. Sets it to <mark style="color:purple;">Public</mark> or <mark style="color:purple;">Private</mark>. If Private only Roster Managers will be able to move players to that Group.

## Modifying Groups

<mark style="color:blue;">**/roster groups modify**</mark> <mark style="color:purple;">**group:**</mark> `Group [...Options]`

* **group** - Select a Group to modify.
* **name** - Change the name of the Group.
* **order** - Change the order of the Group using the <mark style="color:purple;">number</mark> 1 as the lowest.
* **group\_role** - Give the Group a Role.
* **selectable** - Whether to allow Members to select this Group. Sets it to <mark style="color:purple;">Public</mark> or <mark style="color:purple;">Private</mark>. If Private only Roster Managers will be able to move players to that Group.
* **delete\_role** - Where to delete the Role of the Group. To delete set <mark style="color:purple;">True</mark>.
* **delete\_group** - Whether to delete the Group. To delete set <mark style="color:purple;">True</mark>**.**

{% hint style="info" %}
See [List Rosters and Groups](/features/rosters/list-rosters-and-groups#getting-all-rosters-and-groups) to view all groups.
{% endhint %}


# Exporting Rosters

A detailed explanation of how to export rosters to spreadsheets.

<mark style="color:blue;">**/export rosters**</mark> <mark style="color:purple;">**category:**</mark> `WAR or CWL`

Category is optional!

Exports the Rosters to a Google Spreadsheet, allows you to view this on the Web and allows you to download it.

## Sheets

It generates a single Google Spreadsheet containing one sheet per Roster (titled with the roster name), plus an "All Members" sheet and a "Missing Members" sheet.

### Roster Sheet

With the following Columns:

* **Player Name**
* **Player Tag**
* **In Clan?** - If the Player is currently on the Roster Clan
* **Current Clan** - Where the Player currently is
* **Current ClanTag** - The Clan Tag of the Current Clan
* **Discord** - The Discord User Name
* **War Preference** - In or Out of War
* **Group** - The selected Group in the Roster
* **Town Hall**
* **Combined Heroes** - The combined Hero Levels

### All Members Sheet

Aggregates every roster's signed-up players. Contains all the same columns as the Roster Sheet, plus two additional columns: **Roster** (the roster name) and **Roster Clan**.

### Missing Members Sheet

Shows all Players in the Roster Clans that aren't in any of the Rosters with the following columns

* **Player Name**
* **Player Tag**
* **Town Hall**
* **Discord**
* **Clan**
* **Clan Tag**


# Bot Personalizer

Customize the identity of your bot on your Discord server.

Give your bot a unique identity that matches your server's theme. You can either go for a **simple setup** (just change the avatar and nickname — no technical steps required) or a **full custom bot setup** using your own Discord bot token.

{% hint style="info" %}
**Subscription Required:** This feature requires an active [Gold tier Patreon subscription](https://www.patreon.com/clashperk) or a [Lifetime subscription](https://www.paypal.com/ncp/payment/9MUE99PA4JYN2).
{% endhint %}

***

## Quick Customize (No Token Required)

Don't want to deal with the Discord Developer Portal? No problem. You can still give ClashPerk a personalized look on your server without creating a custom bot.

1. Run the `/bot-personalizer` command in your server.
2. Click the **Quick Customize** button.
3. A modal will appear — upload an avatar image and enter a nickname (both are required).
4. Submit the modal and the changes will apply instantly.

**Avatar requirements:** PNG, GIF, JPG, or WEBP | 1024×1024 (1:1 aspect ratio) | Max 10MB

This approach keeps things simple — no bot token, no emoji servers, and no technical setup needed.

***

## Full Custom Bot Setup (Token Required)

For a completely branded experience — your own bot name, avatar, and presence — you can connect a custom Discord bot using a token. This setup also requires inviting your bot to our 14 custom emoji servers so that game icons display correctly.

{% hint style="warning" %}
**Security Notice:** Your bot token is a highly sensitive credential. Never share it with anyone. If you suspect it has been compromised, reset it immediately from the Discord Developer Portal.
{% endhint %}

### How to Create and Set Up a Custom Bot

**Step 1 — Run the bot-personalizer command**

Run `/bot-personalizer` in your Discord server and click the **Developer Portal** button to open the Discord Developer Portal in your browser.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-a2e4abae63f0202c2efa495bbbfa7f4127dd113f%2FStep%201.png?alt=media" alt=""><figcaption><p>Step 1 — Run /bot-personalizer and click Developer Portal</p></figcaption></figure>

**Step 2 — Create a new application**

On the Discord Developer Portal Applications page, click **New Application** in the top-right corner.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-7e09af1923374c430e68d94a0dc833f21d75bdae%2FStep%202.png?alt=media" alt=""><figcaption><p>Step 2 — Click New Application</p></figcaption></figure>

**Step 3 — Name your bot**

Enter a name for your bot (you can change it later), tick the **Terms of Service** checkbox, then click **Create**.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-d0e9c66388ad531b6d3bc657c9295d26d3aaf8a2%2FStep%203.png?alt=media" alt=""><figcaption><p>Step 3 — Enter a name, accept ToS, and click Create</p></figcaption></figure>

**Step 4 — Your application is created**

Your application is now created. You can optionally set an avatar image here. Make note of your **Application ID** — you may need it later.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-a74a364f9147eebc4205d595b9662be8ab05e120%2FStep%204.png?alt=media" alt=""><figcaption><p>Step 4 — Application created (optionally set an avatar)</p></figcaption></figure>

**Step 5 — Navigate to OAuth2**

After setting your avatar (if desired), click **Save Changes**, then navigate to the **OAuth2** section in the left sidebar.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-9209b7787bb58a78f29f0ce58b2ce177c671aea6%2FStep%205.png?alt=media" alt=""><figcaption><p>Step 5 — Navigate to the OAuth2 section</p></figcaption></figure>

**Step 6 — Open the URL Generator**

Under OAuth2, click **URL Generator** in the left sidebar.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-d2c420fbdbdd1fd5e1a6b7cce66d173f7e92b9f6%2FStep%206.png?alt=media" alt=""><figcaption><p>Step 6 — Open OAuth2 → URL Generator</p></figcaption></figure>

**Step 7 — Generate an invite URL**

Under **Scopes**, select **bot**. Under **Bot Permissions**, select **Administrator**. Copy the generated URL at the bottom of the page.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-f71d4337989b9c6dc93394738fb6af9d048f31d4%2FStep%207.png?alt=media" alt=""><figcaption><p>Step 7 — Select bot scope + Administrator permission, copy the URL</p></figcaption></figure>

**Step 8 — Open the invite URL**

Open a **new browser tab** and paste the copied URL into the address bar.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-afb5b930d2d008e53e25ce2a20b3b9e1c276617f%2FStep%208.png?alt=media" alt=""><figcaption><p>Step 8 — Open a new tab and paste the URL</p></figcaption></figure>

**Step 9 — Add the bot to your server**

Select your Discord server from the dropdown, click **Continue**, then **Authorize**. Once done, close this tab and return to the Developer Portal.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-a7186ebc356619b5874ce80967c60dffc9cd314d%2FStep%209.png?alt=media" alt=""><figcaption><p>Step 9 — Select your server, authorize, then close the tab</p></figcaption></figure>

**Step 10 — Navigate to the Bot tab and reset the token**

In the Developer Portal, go to the **Bot** section in the left sidebar and click **Reset Token**. Confirm when prompted.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-3a47016b1f799bcdcd821649db285576bbf205d0%2FStep%2010.png?alt=media" alt=""><figcaption><p>Step 10 — Go to Bot tab and click Reset Token</p></figcaption></figure>

**Step 11 — Copy the bot token**

A token will be displayed — **copy it immediately**, as it will not be shown again. Scroll down to configure additional bot settings.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-92a37d2248f225b708001c268e5186f171c601e4%2FStep%2011.png?alt=media" alt=""><figcaption><p>Step 11 — Copy the token (it won't be shown again)</p></figcaption></figure>

**Step 12 — Configure bot settings**

Scroll down on the Bot page and do the following:

* **Disable** the **Public Bot** toggle so only you can add it to servers.
* **Enable** all three Privileged Gateway Intents: **Presence Intent**, **Server Members Intent**, and **Message Content Intent**.

Click **Save Changes**.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-2f34494fb811ec4380d10a061a4caa3be408ebe6%2FStep%2012.png?alt=media" alt=""><figcaption><p>Step 12 — Disable Public Bot and enable all three intents</p></figcaption></figure>

**Step 12.5 — Configure Installation settings**

Navigate to the **Installation** section in the left sidebar. Make sure both **User Install** and **Guild Install** are checked under Installation Contexts, and set the **Install Link** to **None**.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2FGJrTd0v2LOoqVwPjK93P%2Fstep6.png?alt=media&amp;token=6620e82d-faa1-42ce-b8ec-78a6300c4b0f" alt=""><figcaption><p>Step 12.5 — Enable both installation contexts and set Install Link to None</p></figcaption></figure>

**Step 13 — Return to Discord and click Let's start!**

Go back to your Discord server where you ran `/bot-personalizer` and click the **Let's start!** button in the ClashPerk message.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-f0980bd3aa228fa076e2775c35f30f0a3a3f086d%2FStep%2014.png?alt=media" alt=""><figcaption><p>Step 13 — Click Let's start! in your Discord server</p></figcaption></figure>

**Step 14 — Submit your bot token**

A **Bot Personalizer** modal will appear. Paste the token you copied in Step 11 into the **Bot Token** field and click **Submit**.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-d6f534801572b41b186c01b3e6c5021bc54d5232%2FStep%2015.png?alt=media" alt=""><figcaption><p>Step 14 — Paste the bot token and click Submit</p></figcaption></figure>

**Step 15 — Your bot is live!**

ClashPerk will set up your custom bot within a few minutes. Once deployed, your bot will appear online in your server with its own name and avatar.

<figure><img src="https://3640786437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F30S7oRff9VrT00jdqJ1p%2Fuploads%2Fgit-blob-1125ef540aaa0b3efdac3c6488a012f3ba989a34%2FStep%2016.png?alt=media" alt=""><figcaption><p>Step 15 — Your custom bot is now online</p></figcaption></figure>

Finally, invite your custom bot to our emoji servers so it can display game icons properly. Join our [support server](https://discord.gg/ppuppun) to get the invite links to the emoji servers.


# Flags (Ban/Strike)

A flag serves as a warning for breaking rules, alerting users to potential consequences like bans or strikes. It is a mechanism to maintain order and uphold community standards.

## Ban

When a player receives a banned flag, it usually means they have violated the community guidelines to such an extent that they are no longer allowed in the clan or family. This could be due to severe misconduct, cheating, harassment, or other serious offenses.

<mark style="color:blue;">**/flag create**</mark> `[BAN]` `[PLAYER]` `[...REASON]`

### Getting Alerts

When a banned player joins your clan or family, the bot can notify you in the Flag Alert Log.

<mark style="color:blue;">**/setup server-logs**</mark> `[Flag Alert Log]`

***

## Strike

A strike is a soft warning — a milder penalty than a ban. It serves as a notification to the user that their behavior has been noted and is not acceptable according to the clan's rules. Strikes are often used for minor infractions or as a first step in a progressive disciplinary system.

<mark style="color:blue;">**/flag create**</mark> `[STRIKE]` `[PLAYER]` `[...REASON]` `[EXPIRY_DAYS]`

***

### Other options

These options work on any flag type (`/flag create`):

* **flag\_expiry\_days** - Number of days after which the flag automatically expires. Applies to both bans and strikes (most useful for strikes).
* **flag\_impact** - The weight/severity of the flag.
* **dm\_user** - Whether to DM the player when the flag is added.


# Auto Role

Automatically add Roles in Discord based on the in-game Roles, Leagues, Town Halls, etc.

### Clan Roles

Roles will be given based on the in-game clan role. `/autorole clan-roles` is a single command with a named option for each role:

<mark style="color:blue;">**/autorole clan-roles**</mark> <mark style="color:purple;">**clans:**</mark> [`#CLAN_TAG`](#user-content-fn-1)[^1] <mark style="color:purple;">**leader\_role:**</mark> `@role` <mark style="color:purple;">**co\_leader\_role:**</mark> `@role` <mark style="color:purple;">**elder\_role:**</mark> `@role` <mark style="color:purple;">**member\_role:**</mark> `@role` <mark style="color:purple;">**everyone\_role:**</mark> `@role` <mark style="color:purple;">**only\_verified:**</mark> [`True/False`](#user-content-fn-2)[^2]

***

### Town Hall Roles

Roles will be given based on Town Hall levels.

<mark style="color:blue;">**/autorole town-hall**</mark> `[TH8_ROLE]` `[TH10_ROLE]` `[MORE...]`

***

### Builder Hall Roles

Roles will be given based on Builder Hall levels (BH1–BH10).

<mark style="color:blue;">**/autorole builder-hall**</mark> `[BH5_ROLE]` `[BH8_ROLE]` `[MORE...]`

***

### League Roles

Roles will be given based on the player's Home Village league.

<mark style="color:blue;">**/autorole leagues**</mark> `[CHAMPION_ROLE]` `[TITAN_ROLE]` `[LEGEND_ROLE]`

***

### Builder Base League Roles

Roles will be given based on the player's Builder Base league (Wood, Clay, Stone, Copper, Brass, Iron, Steel, Titanium, Platinum, Emerald, Ruby, Diamond).

<mark style="color:blue;">**/autorole builder-leagues**</mark> `[WOOD_ROLE]` `[IRON_ROLE]` `[DIAMOND_ROLE]` `[MORE...]`

***

### War Role

A role given to members who are currently in the war lineup for a specific clan.

<mark style="color:blue;">**/autorole wars**</mark> <mark style="color:purple;">**clan:**</mark> `#CLAN_TAG` <mark style="color:purple;">**role:**</mark> `[WAR_ROLE]`

Each clan can have its own war role. The role is assigned when war starts and removed when it ends.

***

### EOS Push Role

A role given to members who are participating in an End-of-Season push for selected clans.

<mark style="color:blue;">**/autorole eos-push**</mark> <mark style="color:purple;">**role:**</mark> `[EOS_PUSH_ROLE]` <mark style="color:purple;">**clans:**</mark> `#CLAN_TAG`

***

### Family Roles

`/autorole family` is a single command — set any combination of the named options below in one call.

<mark style="color:blue;">**/autorole family**</mark> <mark style="color:purple;">**family\_role:**</mark> `@role` <mark style="color:purple;">**exclusive\_family\_role:**</mark> `@role` <mark style="color:purple;">**guest\_role:**</mark> `@role` <mark style="color:purple;">**verified\_role:**</mark> `@role` <mark style="color:purple;">**account\_linked\_role:**</mark> `@role` <mark style="color:purple;">**family\_leaders\_role:**</mark> `@role`

| Option                  | Role is given when…                                                                 |
| ----------------------- | ----------------------------------------------------------------------------------- |
| `family_role`           | Any of their linked accounts is in the family                                       |
| `exclusive_family_role` | All of their linked accounts are in the family                                      |
| `guest_role`            | None of their accounts are in the family                                            |
| `verified_role`         | They verified an account with the `/verify` command                                 |
| `account_linked_role`   | They have at least one linked account                                               |
| `family_leaders_role`   | They are a Leader or Co-Leader of a family clan (supports selecting multiple roles) |

***

### List Configured Roles

View all roles currently configured in the server.

<mark style="color:blue;">**/autorole list**</mark>

***

### Refresh Roles

Manually trigger a role refresh for all members.

<mark style="color:blue;">**/autorole refresh**</mark>

***

### Disable a Role Type

Remove the configuration for a specific role type without affecting other settings.

<mark style="color:blue;">**/autorole disable**</mark> <mark style="color:purple;">**type:**</mark> `town-hall`

***

## <mark style="color:yellow;">Additional Settings</mark>

{% tabs %}
{% tab title="Role Removal Delay" %} <mark style="color:yellow;">If people temporarily leave their home clans for any reason, they lose their roles. To address this issue, a role removal delay can be enabled.</mark>\ <mark style="color:yellow;">Their roles will not be removed immediately but will remain for a specified period.</mark>\ <mark style="color:yellow;">However, if they do not return within this time frame, their roles will be removed.</mark>\
\ <mark style="color:blue;">**/autorole config**</mark> `role_removal_delays: Off/Duration`
{% endtab %}

{% tab title="Role Addition Delay" %} <mark style="color:yellow;">A delay can be set before roles are added to new members. Useful if you want to verify a member has settled in before granting roles.</mark>\
\ <mark style="color:blue;">**/autorole config**</mark> `role_addition_delays: Off/Duration`
{% endtab %}

{% tab title="Delay Exclusion" %} <mark style="color:yellow;">Certain role types can be excluded from the removal delay — for example, guest roles or league roles can still be removed instantly even when a global delay is active.</mark>\
\ <mark style="color:blue;">**/autorole config**</mark> `delay_exclusion_roles: town-hall-roles / league-roles / guest-role / ...`
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Token Verification" %} <mark style="color:yellow;">Token verification can be enabled to ensure that only legitimate users receive</mark> [#clan-roles](#clan-roles "mention")\ <mark style="color:yellow;">Verification is performed using the</mark> <mark style="color:yellow;">**/verify**</mark> <mark style="color:yellow;">command with an in-game API token.</mark>\
\ <mark style="color:blue;">**/autorole config**</mark> `verified_only_clan_roles: Yes/No`
{% endtab %}

{% tab title="Allow Non-Linked Members" %} <mark style="color:yellow;">By default, members without a linked account are skipped. Enable this to still assign applicable roles to unlinked members.</mark>\
\ <mark style="color:blue;">**/autorole config**</mark> `allow_not_linked: Yes/No`
{% endtab %}

{% tab title="Toggle Auto Mode" %} <mark style="color:yellow;">Auto Role updates roles whenever changes are detected in the game. This behavior can be disabled for manual control using the /autorole refresh command.</mark>\
\ <mark style="color:blue;">**/autorole config**</mark> `auto_update_roles: Yes/No`
{% endtab %}

{% tab title="Force Refresh" %} <mark style="color:yellow;">When enabled, every role refresh cycle re-evaluates all members regardless of whether changes were detected. Useful for servers where role drift occurs.</mark>\
\ <mark style="color:blue;">**/autorole config**</mark> `always_force_refresh_roles: Yes/No`
{% endtab %}
{% endtabs %}

[^1]: One or multiple clans can be selected.

[^2]: If enabled, roles will be given to verified players only.


# Logs

A detailed explanation of all Logs

Logs are automatic messages posted by ClashPerk.

You can enable them per clan. You can send each log to its own channel or thread.

### Set up logs

Run <mark style="color:blue;">**/setup clan-logs**</mark> <mark style="color:purple;">**clan:**</mark> `#CLAN_TAG` <mark style="color:purple;">**channel:**</mark> `#channel`

{% hint style="info" %}
Logs are not truly real-time. ClashPerk polls the official API, so short delays can happen.

[FAQ](/faq#how-does-clashperk-track-game-data)
{% endhint %}

***

## <mark style="color:green;">Clan Logs</mark>

#### <mark style="color:green;">Clan Achievements Log</mark>

Posts when the clan reaches a milestone.

* Clan level up, War League promotion/demotion, Capital League promotion/demotion, Capital Hall level up.

#### <mark style="color:green;">Donation Log</mark>

Tracks troop donations.

{% tabs %}
{% tab title="Instant" %}
Posts whenever someone donates or receives troops.
{% endtab %}

{% tab title="Daily" %}
Posts a daily donation summary.
{% endtab %}

{% tab title="Weekly" %}
Posts every Monday.
{% endtab %}

{% tab title="Monthly" %}
Posts on the last Monday of each month.
{% endtab %}
{% endtabs %}

#### <mark style="color:green;">Clan Games Embed Log</mark>

Posts a Clan Games leaderboard message. It updates itself throughout the event.

* Shows points, average, and tier progress.

#### <mark style="color:green;">Last Seen Embed Log</mark>

Posts one message and keeps it updated. Updates run approximately every 30 minutes.

* Shows estimated activity / last-seen status.
* Uses signals like donations, trophy changes, clan games, capital activity, etc.

See [How does last seen work?](/faq#how-does-last-seen-work).

#### <mark style="color:green;">Legend Attacks Daily Summary Log</mark>

Posts a daily legend league recap.

* Shows offense gained, defense lost, and final placement.

{% hint style="info" %}
Data can be off when offense and defense happen between two API polls.
{% endhint %}

***

## <mark style="color:purple;">Capital Logs</mark>

#### <mark style="color:purple;">Clan Capital Weekly Summary Log</mark>

Posts after the raid weekend ends.

* Shows total raid loot and capital gold contribution.
* Includes a graphic similar to the in-game summary.

#### <mark style="color:purple;">Capital Gold Contribution Log</mark>

Posts each time a member contributes capital gold.

#### <mark style="color:purple;">Capital Gold Raid Log</mark>

Posts each time a member completes a capital raid attack.

***

## <mark style="color:red;">War Logs</mark>

#### <mark style="color:red;">War Attack Log</mark>

Posts a message for every attack made during a Clan War.

#### <mark style="color:red;">CWL Attack Log</mark>

Posts a message for every attack made during CWL.

#### <mark style="color:red;">War Embed Log</mark>

Posts one embed per war and updates it during the war.

* Shows recent attacks, war state, war size, and key stats.
* Includes a Town Hall breakdown.

#### <mark style="color:red;">War Missed Attacks Log</mark>

Posts a list of players who missed attacks.

* Splits players by 1 missed vs 2 missed.

#### <mark style="color:red;">CWL Embed Log</mark>

Posts one embed per CWL round and updates it.

#### <mark style="color:red;">CWL Missed Attacks Log</mark>

Posts a list of players who missed their CWL attacks.

#### <mark style="color:red;">CWL Lineup Change Log</mark>

Logs lineup changes as they happen.

* Shows who was added and who was removed.

#### <mark style="color:red;">CWL Monthly Summary Log</mark>

Posts a graphic summarizing the CWL season placements.

***

## <mark style="color:blue;">Player Logs</mark>

#### <mark style="color:blue;">Member Join/Leave Log</mark>

Tracks members joining and leaving your clan.

* **On join**: Town Hall, trophies, hero levels, war stars, rushed %, join source, member count, time.
* **On leave**: Town Hall, trophies, donations at leave, and join source (if known).

#### <mark style="color:blue;">Role Change Log</mark>

Tracks in-game promotions and demotions.

* Shows who changed role, the old/new role, and when.

#### <mark style="color:blue;">Name Change Log</mark>

Posts when a member changes their in-game name.

#### <mark style="color:blue;">Town Hall Upgrade Log</mark>

Posts when a member upgrades their Town Hall.

* Also shows the % of troop upgrades remaining.
* Optional: ping a role via `ping_role`.

#### <mark style="color:blue;">War Preference Log</mark>

Posts when a member changes war preference.

* Shows opt-in vs opt-out.

#### <mark style="color:blue;">Ranked Battle League Change Log</mark>

Posts when a member's Builder Base league changes.

* Shows the old and new league.


# Reminders

Automatically ping members when time is running out for Clan Wars, Capital Raids, or Clan Games.

Reminders automatically notify members in a Discord channel when there is limited time left in an event. You can set up multiple reminders per event type, each at a different time threshold.

Supported event types:

* **Clan Wars** — ping members who haven't used all attacks before war ends
* **Capital Raids** — ping members who haven't used all raid attacks before the weekend closes
* **Clan Games** — ping members who haven't reached a points threshold before clan games ends

***

### Create a Reminder

<mark style="color:blue;">**/reminders create**</mark> <mark style="color:purple;">**type:**</mark> `Clan Wars` <mark style="color:purple;">**duration:**</mark> `6h` <mark style="color:purple;">**clans:**</mark> `#CLAN_TAG` <mark style="color:purple;">**message:**</mark> `Attack now!` <mark style="color:purple;">**channel:**</mark> `#channel`

| Option                     | Description                                                                                                                                                                                                              |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` *(required)*        | `Clan Wars`, `Capital Raids`, or `Clan Games`                                                                                                                                                                            |
| `duration` *(required)*    | Time remaining when the ping fires — e.g. `1h`, `6h`, `12h`, `1d`. Minimum 15 minutes. Maximum depends on type: **Clan Wars** `48h` (and must be a multiple of 15 minutes), **Capital Raids** `3d`, **Clan Games** `6d`. |
| `clans` *(required)*       | Clan tags or aliases to target                                                                                                                                                                                           |
| `message` *(required)*     | Custom message included in the reminder notification                                                                                                                                                                     |
| `channel`                  | Channel to post the reminder in (defaults to current channel)                                                                                                                                                            |
| `exclude_participant_list` | *(Clan Wars only)* Send only the message without listing missing attackers                                                                                                                                               |

{% hint style="info" %}
You can create multiple reminders for the same event at different durations (e.g. 12h and 2h remaining).

**Special durations for Clan Wars:**

* `48h` — fires when the war starts (preparation day begins)
* `24h` — fires when the battle day starts
* `0h` — fires exactly when the war ends

At `0h`, `24h`, and `48h` the participant list is hidden automatically — only your custom message is sent.
{% endhint %}

***

### List Reminders

<mark style="color:blue;">**/reminders list**</mark> <mark style="color:purple;">**type:**</mark> `Clan Wars`

Shows all configured reminders for the selected type. Use this to find the **Reminder ID** needed for editing or deleting.

***

### Edit a Reminder

<mark style="color:blue;">**/reminders edit**</mark> <mark style="color:purple;">**type:**</mark> `Clan Wars` <mark style="color:purple;">**id:**</mark> `REMINDER_ID` <mark style="color:purple;">**duration:**</mark> `3h`

Use `/reminders list` to get the reminder ID.

***

### Delete a Reminder

<mark style="color:blue;">**/reminders delete**</mark> <mark style="color:purple;">**type:**</mark> `Clan Wars` <mark style="color:purple;">**id:**</mark> `REMINDER_ID`

***

### Send an Instant Reminder

<mark style="color:blue;">**/reminders now**</mark> <mark style="color:purple;">**type:**</mark> `Clan Wars` <mark style="color:purple;">**clans:**</mark> `#CLAN_TAG` <mark style="color:purple;">**message:**</mark> `Last call!`

Sends a one-off reminder immediately without waiting for a scheduled trigger. The `message` option is required. Useful for manually pinging before an important deadline.

***

### Ping Exclusion (OptIn / OptOut)

<mark style="color:blue;">**/reminders config**</mark>

Controls which members receive reminder pings. You can assign a role per event type and choose between two modes:

* **OptIn** — only members with the assigned role are pinged
* **OptOut** — all members are pinged *except* those with the assigned role

This lets members or leadership control who gets notified without editing each reminder individually.


# Nickname

Automatically format Discord nicknames using in-game data.

ClashPerk can automatically set Discord nicknames based on a custom template. You can define separate formats for family members and non-family members.

<mark style="color:blue;">**/nickname config**</mark>

***

### Family Nickname Format

Applied to members who are in the family (linked to a tracked clan).

<mark style="color:blue;">**/nickname config**</mark> <mark style="color:purple;">**family\_nickname\_format:**</mark> `{TH} | {NAME} | {ROLE}`

Must include at least one name variable: `{PLAYER_NAME}` or `{DISCORD_NAME}` or `{DISCORD_USERNAME}`.

### Non-Family Nickname Format

Applied to members who are linked but not in any tracked clan.

<mark style="color:blue;">**/nickname config**</mark> <mark style="color:purple;">**non\_family\_nickname\_format:**</mark> `{NAME}`

Cannot include clan-specific variables like `{CLAN}`, `{ALIAS}`, or `{ROLE}`.

Set either format to `none` to disable it.

***

### Available Variables

| Variable                             | Description                                                                                               |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `{NAME}` or `{PLAYER_NAME}`          | In-game player name                                                                                       |
| `{TH}` or `{TOWN_HALL}`              | Town Hall level                                                                                           |
| `{TH_SMALL}` or `{TOWN_HALL_SMALL}`  | Town Hall level (smaller format)                                                                          |
| `{ROLE}` or `{CLAN_ROLE}`            | In-game clan role (default labels: `Lead`, `Co-Lead`, `Eld`, `Mem` — customizable, see Role Labels below) |
| `{ALIAS}` or `{CLAN_ALIAS}`          | Clan alias                                                                                                |
| `{ALIASES}` or `{CLAN_ALIASES}`      | All clan aliases                                                                                          |
| `{CLAN}` or `{CLAN_NAME}`            | Clan name                                                                                                 |
| `{DISCORD}` or `{DISCORD_NAME}`      | Discord display name                                                                                      |
| `{USERNAME}` or `{DISCORD_USERNAME}` | Discord username                                                                                          |

**Example formats:**

* `{NAME} | {TH} | {ROLE}` → `WarriorKing | TH16 | Co-Lead`
* `{ROLE} | {TH} | {NAME}` → `Lead | TH16 | WarriorKing`
* `{NAME} | {TH} | {ALIAS}` → `WarriorKing | TH16 | WR`

***

### Role Labels

The `{ROLE}` variable uses short labels. You can customize them from the `/nickname config` menu.

| Role      | Default Label |
| --------- | ------------- |
| Leader    | `Lead`        |
| Co-Leader | `Co-Lead`     |
| Elder     | `Eld`         |
| Member    | `Mem`         |

***

### Auto Updates

<mark style="color:blue;">**/nickname config**</mark> <mark style="color:purple;">**change\_nicknames:**</mark> `Yes`

When enabled, nicknames update automatically alongside Auto Role.

{% hint style="info" %}
Auto Role must be enabled for nickname changes to run automatically. Use `/autorole refresh` to manually trigger a refresh, or nicknames also update when an account is linked.
{% endhint %}


# Discord Events

Automatically create Discord scheduled events for Clash of Clans game events.

ClashPerk can automatically create Discord scheduled events so your members always know when the next game event starts.

<mark style="color:blue;">**/setup events**</mark>

Requires the bot to have **Create Events** and **Manage Events** permissions.

***

### Supported Events

| Event                 | Description                                    |
| --------------------- | ---------------------------------------------- |
| Clan Games            | Created when Clan Games starts                 |
| Clan Games (Ending)   | Created as Clan Games approaches the end       |
| CWL                   | Created when CWL battle days begin             |
| CWL (Ending)          | Created as CWL approaches the end              |
| CWL Signup (Ending)   | Created as CWL signup window closes            |
| Raid Weekend          | Created when the Capital Raid weekend starts   |
| Raid Weekend (Ending) | Created as the Raid weekend approaches the end |
| Season Reset          | Created before the season trophy reset         |

You can toggle each event type individually and set a custom image and location per type.

***

### Disable

<mark style="color:blue;">**/setup events**</mark> <mark style="color:purple;">**disable:**</mark> `Yes`


# Clan Categories

Organize your clans into named groups for easier navigation.

Categories let you group clans into named sections (e.g. "Main", "Farm", "ESPORTS"). They appear in command clan selectors, making it easier to navigate servers with many clans.

***

### Create a Category

<mark style="color:blue;">**/category create**</mark> <mark style="color:purple;">**category\_name:**</mark> `Main` <mark style="color:purple;">**category\_order:**</mark> `1`

`category_order` controls where the category appears in the list. If omitted, it is added at the end.

***

### Edit a Category

<mark style="color:blue;">**/category edit**</mark> <mark style="color:purple;">**category:**</mark> `[ID]` <mark style="color:purple;">**category\_name:**</mark> `War Clans`

Use `/category list` to find the category ID.

***

### Delete a Category

<mark style="color:blue;">**/category delete**</mark> <mark style="color:purple;">**category:**</mark> `[ID]`

***

### List Categories

<mark style="color:blue;">**/category list**</mark>

***

### Reorder Clans and Categories

Fine-grained reordering of clans within categories is available on the dashboard at [clashperk.com/clans](https://clashperk.com/clans).


# Clan Alias

Assign short, custom names to your clans. With aliases, you can quickly reference clans in commands, saving time and ensuring smooth management.

Autocomplete is great, but it can sometimes take a moment to appear. Clan aliases solve this problem by offering a faster alternative. Instead of waiting for autocomplete to load, simply type the alias and hit Enter.

Example:

For a series of clans like Air Hounds, Air Hounds 2, and Air Hounds 3, you could assign aliases like AH, AH2, and AH3.

For example, to refer to Air Hounds directly:

```css
/clan tag: AH
```

Clan aliases are handy for commands like /summary and /export, where you can enter multiple aliases to search for specific clans.

```css
/summary clans: AH AH2
```

Aliases can also be used in rosters and nicknames, making them a powerful tool for efficient clan management.

### Create Alias

```css
/alias create clan: YOUR_CLAN alias_name: AH
```


# 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.

> 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; get full channel access including Manage Messages |
| **Viewer roles** | Can see and send messages in the ticket but cannot manage it                      |
| **Add roles**    | Automatically added to the ticket creator when the ticket opens                   |
| **Remove roles** | Automatically removed from the ticket creator when the ticket opens               |

#### 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 add`                                                 |
| **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 for staff when the ticket is created                                                      |
| **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.

| Category   | When used                                 |
| ---------- | ----------------------------------------- |
| **Open**   | Channel is placed here when first created |
| **Sleep**  | Channel moves here when put to sleep      |
| **Closed** | Channel moves here when closed            |

#### 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}`         | Clan leader name                   |
| `{clan_leader_mention}` | Clan leader mention                |
| `{ticket_count}`        | Ticket number                      |
| `{ticket_status}`       | Current ticket status              |
| `{server_name}`         | Discord server name                |

***

### 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**  | A ticket channel is deleted (transcript attached)                         |

***

### 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`

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

Posts the panel embed and button to the target channel. 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            |
| <mark style="color:blue;">**/ticket-close**</mark>          | Close the ticket — moves to closed category                                                |
| <mark style="color:blue;">**/ticket-delete**</mark>         | Permanently delete the ticket channel (generates a transcript first)                       |
| <mark style="color:blue;">**/ticket-info**</mark>           | Show ticket details: creator, linked account, status, panel, type, trophies, league        |
| <mark style="color:blue;">**/ticket-add**</mark> `[member]` | Add a Discord member to the ticket channel                                                 |

***

## 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               | Toggle DM notifications when the ticket status changes                   |
| **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                           |
| **View Account**  | Anyone               | Show linked Clash of Clans account stats                                 |
| **Delete Ticket** | Anyone with access   | Close and delete the ticket (asks for confirmation first)                |

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

***

## 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.


# Bot Manager

The bot manager role allows anyone to use all the bot's administrative commands without any admin permissions.

A user-defined role that allows anyone to use all administrative commands without Manage Server permission.

<mark style="color:blue;">**/config**</mark> <mark style="color:purple;">**manager\_role:**</mark> `@Bot Manager`

***

## Other Manager Roles

Other manager roles can be set up for more specific administrative purposes, such as managing rosters, linking users and refreshing roles, or flagging users.

<mark style="color:blue;">**/config**</mark> <mark style="color:purple;">**roster\_manager\_role:**</mark> `@Roster Manager`

<mark style="color:blue;">**/config**</mark> <mark style="color:purple;">**links\_manager\_role:**</mark> `@Links Manager`

<mark style="color:blue;">**/config**</mark> <mark style="color:purple;">**flags\_manager\_role:**</mark> `@Flags Manager`


# Whitelist

Whitelist a role or user to use specific commands.

<mark style="color:red;">You can whitelist a role or user. Once whitelisted, only that role or user can use the command — others will be blocked unless they have a manager role or the required permissions.</mark>

<mark style="color:red;">The whitelist applies to commands only and does not extend to buttons or select menus. For control over both, use manager roles instead.</mark>

<mark style="color:blue;">**/whitelist**</mark> <mark style="color:purple;">**user\_or\_role:**</mark> `@User` <mark style="color:purple;">**command:**</mark> `/link create`


# Autocomplete

Autocomplete is a feature that helps you select your clans or accounts while executing a command.

User-linked or Server-linked clans or accounts are always prioritized and will always be at the top of the list. After that, your recently searched clans or accounts are suggested.

> Recently searched clans and accounts cannot currently be removed.


# Commands


# /activity

Shows a graph of hourly-active clan members.

Shows a graph of hourly-active clan members.

## Options

| Name       | Description                                                                           |
| ---------- | ------------------------------------------------------------------------------------- |
| `clans`    | Clan tags or aliases (Maximum 3)                                                      |
| `days`     | The number of days is displayed in the graph.                                         |
| `limit`    | Number of clans to show in the graph.                                                 |
| `timezone` | Search timezone by city or country. (e.g. London, New York, Singapore, India, Sydney) |


# /alias


# /alias create

Creates a clan alias (short code or abbreviation) or clan nickname.

Creates a clan alias (short code or abbreviation) or clan nickname.

## Options

| Name            | Description                         |
| --------------- | ----------------------------------- |
| `clan`          | Clan tag or name or alias.          |
| `alias_name`    | Name of the alias.                  |
| `clan_nickname` | Nickname of the clan (Experimental) |


# /alias delete

Deletes a clan alias.

Deletes a clan alias.

## Options

| Name    | Description                       |
| ------- | --------------------------------- |
| `alias` | Tag of a clan or name of an alias |


# /alias list

List all clan aliases.

List all clan aliases.


# /army

Parse an army composition link.

Parse an army composition link.

## Options

| Name        | Description                     |
| ----------- | ------------------------------- |
| `link`      | Army composition link.          |
| `army_name` | An optional name for this army. |
| `tips`      | Some tips (type anything)       |


# /attacks

Displays attack and defense info of clan members.

Displays attack and defense info of clan members.

## Options

| Name     | Description                     |
| -------- | ------------------------------- |
| `clan`   | Clan tag or name or alias.      |
| `user`   | Clan by @user mention or ID.    |
| `season` | The season to show attacks for. |


# /autorole


# /autorole builder-hall

Manage automatic Builder Hall roles.

Manage automatic Builder Hall roles.

## Options

| Name    | Description           |
| ------- | --------------------- |
| `bh_1`  | Builder Hall 1 role.  |
| `bh_2`  | Builder Hall 2 role.  |
| `bh_3`  | Builder Hall 3 role.  |
| `bh_4`  | Builder Hall 4 role.  |
| `bh_5`  | Builder Hall 5 role.  |
| `bh_6`  | Builder Hall 6 role.  |
| `bh_7`  | Builder Hall 7 role.  |
| `bh_8`  | Builder Hall 8 role.  |
| `bh_9`  | Builder Hall 9 role.  |
| `bh_10` | Builder Hall 10 role. |


# /autorole builder-leagues

Set builder base league roles.

Set builder base league roles.

## Options

| Name       | Description           |
| ---------- | --------------------- |
| `wood`     | Wood league role.     |
| `clay`     | Clay league role.     |
| `stone`    | Stone league role.    |
| `copper`   | Copper league role.   |
| `brass`    | Brass league role.    |
| `iron`     | Iron league role.     |
| `steel`    | Steel league role.    |
| `titanium` | Titanium league role. |
| `platinum` | Platinum league role. |
| `emerald`  | Emerald league role.  |
| `ruby`     | Ruby league role.     |
| `diamond`  | Diamond league role.  |


# /autorole clan-roles

Manage automatic role management for clan roles.

Manage automatic role management for clan roles.

## Options

| Name             | Description                                                                            |
| ---------------- | -------------------------------------------------------------------------------------- |
| `clans`          | Clan tags or aliases to filter clans.                                                  |
| `leader_role`    | The Leader role.                                                                       |
| `co_leader_role` | The Co-Leader role.                                                                    |
| `elder_role`     | The Elder role.                                                                        |
| `member_role`    | The Member role (below Elder)                                                          |
| `everyone_role`  | Clan role for everyone in the clan.                                                    |
| `only_verified`  | Roles will be given to the verified players only. (API token verification is required) |


# /autorole config

Manage automatic roles settings.

Manage automatic roles settings.

## Options

| Name                         | Description                                                      |
| ---------------------------- | ---------------------------------------------------------------- |
| `auto_update_roles`          | Whether to update roles automatically.                           |
| `role_removal_delays`        | Whether to delay the removal of roles.                           |
| `role_addition_delays`       | Whether to delay the addition of roles.                          |
| `delay_exclusion_roles`      | Roles that are excluded from delays.                             |
| `always_force_refresh_roles` | Whether to enforce role refresh for individual users by default. |
| `allow_not_linked`           | Whether to allow not linked players to get roles.                |
| `verified_only_clan_roles`   | Whether to grant clans roles to verified players only.           |


# /autorole disable

Disable automatic clan roles.

Disable automatic role management for clan roles, town hall levels, or leagues.

## Options

| Name    | Description                           |
| ------- | ------------------------------------- |
| `type`  | Type of roles to disable.             |
| `clans` | Clan tags or aliases to filter clans. |


# /autorole eos-push

Set end of season push roles.

Set end of season push roles.

## Options

| Name    | Description                                             |
| ------- | ------------------------------------------------------- |
| `role`  | The end of season push role.                            |
| `clans` | The clans for which to set the end of season push role. |


# /autorole family

Set family roles.

Set family roles.

## Options

| Name                    | Description                                                   |
| ----------------------- | ------------------------------------------------------------- |
| `family_leaders_role`   | Family leaders role (Leaders and Co-Leaders)                  |
| `family_role`           | Family role.                                                  |
| `exclusive_family_role` | Exclusive family role (all linked accounts are in the family) |
| `guest_role`            | Guest role (not in the family)                                |
| `verified_role`         | Verified role (API token verified)                            |
| `account_linked_role`   | Account linked role (account linked but may not be verified)  |


# /autorole leagues

Manage automatic role management for leagues.

Manage automatic role management for leagues.

## Options

| Name                        | Description                                                            |
| --------------------------- | ---------------------------------------------------------------------- |
| `unranked`                  | Unranked league role.                                                  |
| `skeleton`                  | Skeleton league role.                                                  |
| `barbarian`                 | Barbarian league role.                                                 |
| `archer`                    | Archer league role.                                                    |
| `wizard`                    | Wizard league role.                                                    |
| `valkyrie`                  | Valkyrie league role.                                                  |
| `witch`                     | Witch league role.                                                     |
| `golem`                     | Golem league role.                                                     |
| `pekka`                     | Pekka league role.                                                     |
| `titan`                     | Titan league role.                                                     |
| `dragon`                    | Dragon league role.                                                    |
| `electro`                   | Electro league role.                                                   |
| `legend`                    | Legend league role.                                                    |
| `5200_5249`                 | Trophy range 5200 - 5249 role.                                         |
| `5250_5499`                 | Trophy range 5250 - 5499 role.                                         |
| `5500_5749`                 | Trophy range 5500 - 5749 role.                                         |
| `5750_5999`                 | Trophy range 5750 - 5999 role.                                         |
| `6000_8000`                 | Trophy range 6000 - 8000 role.                                         |
| `allow_non_family_accounts` | Whether to give roles to the members that are not in the family clans. |


# /autorole list

List all auto roles and settings.

List all auto roles and settings.


# /autorole refresh

Refresh roles manually.

Refresh roles manually. (Use this command if the roles are not updated automatically)

## Options

| Name            | Description                                       |
| --------------- | ------------------------------------------------- |
| `user_or_role`  | Refresh an individual user or a role.             |
| `is_test_run`   | Test run to see the changes without applying.     |
| `force_refresh` | Whether to bypass delays and force refresh roles. |


# /autorole town-hall

Manage automatic role management for town hall levels.

Manage automatic role management for town hall levels.

## Options

| Name                        | Description                                                            |
| --------------------------- | ---------------------------------------------------------------------- |
| `th_1`                      | Town Hall 1 role.                                                      |
| `th_2`                      | Town Hall 2 role.                                                      |
| `th_3`                      | Town Hall 3 role.                                                      |
| `th_4`                      | Town Hall 4 role.                                                      |
| `th_5`                      | Town Hall 5 role.                                                      |
| `th_6`                      | Town Hall 6 role.                                                      |
| `th_7`                      | Town Hall 7 role.                                                      |
| `th_8`                      | Town Hall 8 role.                                                      |
| `th_9`                      | Town Hall 9 role.                                                      |
| `th_10`                     | Town Hall 10 role.                                                     |
| `th_11`                     | Town Hall 11 role.                                                     |
| `th_12`                     | Town Hall 12 role.                                                     |
| `th_13`                     | Town Hall 13 role.                                                     |
| `th_14`                     | Town Hall 14 role.                                                     |
| `th_15`                     | Town Hall 15 role.                                                     |
| `th_16`                     | Town Hall 16 role.                                                     |
| `th_17`                     | Town Hall 17 role.                                                     |
| `th_18`                     | Town Hall 18 role.                                                     |
| `allow_non_family_accounts` | Whether to give roles to the members that are not in the family clans. |


# /autorole wars

Set automatic war roles.

Set automatic war roles.

## Options

| Name   | Description                             |
| ------ | --------------------------------------- |
| `role` | The war role.                           |
| `clan` | The clan for which to set the war role. |


# /boosts

Displays active super troops of clan members.

Displays active super troops of clan members.

## Options

| Name   | Description                |
| ------ | -------------------------- |
| `clan` | Clan tag or name or alias. |


# /bot-personalizer

Build your own Discord bot!

Build your own Discord bot!

## Options

| Name      | Description                                              |
| --------- | -------------------------------------------------------- |
| `opt_out` | Opt-out from the custom bot and delete related services. |


# /caller


# /caller assign

Set a target for a player in the current war.

Set a target for a player in the current war.

## Options

| Name             | Description                                |
| ---------------- | ------------------------------------------ |
| `defense_target` | The base target # of your opponent.        |
| `offense_target` | The base target # of your clan.            |
| `notes`          | Notes to add to the target.                |
| `hours`          | The number of hours to set the target for. |


# /caller clear

Clear the target for a player in the current war.

Clear the target for a player in the current war.

## Options

| Name             | Description                         |
| ---------------- | ----------------------------------- |
| `defense_target` | The base target # of your opponent. |


# /capital


# /capital contribution

Shows clan capital contribution of clan members.

Shows clan capital contribution of clan members.

## Options

| Name   | Description                         |
| ------ | ----------------------------------- |
| `clan` | Clan tag or name or alias.          |
| `user` | Clan by @user mention or ID.        |
| `week` | The week to show contributions for. |


# /capital raids

Shows raid weekend scores of clan members.

Shows raid weekend scores of clan members.

## Options

| Name   | Description                                   |
| ------ | --------------------------------------------- |
| `clan` | Clan tag or name or alias.                    |
| `user` | Clan by @user mention or ID.                  |
| `week` | Retrieve data for the specified raid weekend. |


# /category


# /category create

Create a new clan category.

Create a new clan category.

## Options

| Name            | Description                |
| --------------- | -------------------------- |
| `category_name` | Name of the clan category. |


# /category delete

Delete a clan category.

Delete a clan category.

## Options

| Name       | Description             |
| ---------- | ----------------------- |
| `category` | Select a clan category. |


# /category edit

Edit a clan category.

Edit a clan category.

## Options

| Name            | Description                |
| --------------- | -------------------------- |
| `category`      | Select a clan category.    |
| `category_name` | Name of the clan category. |


# /category list

List all clan categories.

List all clan categories.


# /clan

Shows comprehensive overview of a clan.

Shows comprehensive overview of a clan.

## Options

| Name            | Description                  |
| --------------- | ---------------------------- |
| `tag`           | Clan tag or name or alias.   |
| `user`          | Clan by @user mention or ID. |
| `by_player_tag` | Get clan by a player tag.    |


# /clan-games

Clan games scoreboard of clan members.

Clan games scoreboard of clan members.

## Options

| Name     | Description                            |
| -------- | -------------------------------------- |
| `clan`   | Clan tag or name or alias.             |
| `user`   | Clan by @user mention or ID.           |
| `season` | The season to show the scoreboard for. |


# /clans

Show all linked clans.

Show all linked clans.

## Options

| Name       | Description               |
| ---------- | ------------------------- |
| `category` | Filter clans by category. |


# /compo

Shows Town Hall composition of a clan.

Shows Town Hall composition of a clan.

## Options

| Name   | Description                  |
| ------ | ---------------------------- |
| `clan` | Clan tag or name or alias.   |
| `user` | Clan by @user mention or ID. |


# /config

Configure server settings.

Configure server settings.

## Options

| Name                  | Description                                                      |
| --------------------- | ---------------------------------------------------------------- |
| `bot_manager_role`    | Role that can manage the bot.                                    |
| `roster_manager_role` | Role that can manage the roster members.                         |
| `flags_manager_role`  | Role that can manage the flags.                                  |
| `links_manager_role`  | Role that can manage the Discord links.                          |
| `color_code`          | Hex color code (e.g #ed4245)                                     |
| `webhook_limit`       | The maximum number of webhooks that can be created in a channel. |


# /cwl


# /cwl attacks

Shows an overview of attacks for different CWL rounds.

Shows an overview of attacks for different CWL rounds.

## Options

| Name     | Description                  |
| -------- | ---------------------------- |
| `clan`   | Clan tag or name or alias.   |
| `season` | CWL season                   |
| `user`   | Clan by @user mention or ID. |


# /cwl lineup

Shows CWL lineup for a round (sorted by town hall and heroes).

Shows CWL lineup for a round (sorted by town hall and heroes).

## Options

| Name   | Description                  |
| ------ | ---------------------------- |
| `clan` | Clan tag or name or alias.   |
| `user` | Clan by @user mention or ID. |


# /cwl members

Shows a list of all CWL participants.

Shows a list of all CWL participants.

## Options

| Name   | Description                  |
| ------ | ---------------------------- |
| `clan` | Clan tag or name or alias.   |
| `user` | Clan by @user mention or ID. |


# /cwl roster

CWL roster and town hall distribution.

CWL roster and town hall distribution.

## Options

| Name   | Description                  |
| ------ | ---------------------------- |
| `clan` | Clan tag or name or alias.   |
| `user` | Clan by @user mention or ID. |


# /cwl round

CWL summary for the current round.

CWL summary for the current round.

## Options

| Name     | Description                  |
| -------- | ---------------------------- |
| `clan`   | Clan tag or name or alias.   |
| `season` | CWL season                   |
| `user`   | Clan by @user mention or ID. |


# /cwl stars

Shows CWL member ranking by stars.

Shows CWL member ranking by stars.

## Options

| Name     | Description                  |
| -------- | ---------------------------- |
| `clan`   | Clan tag or name or alias.   |
| `season` | CWL season                   |
| `user`   | Clan by @user mention or ID. |


# /cwl stats

Shows an overview of all CWL rounds and group standings.

Shows an overview of all CWL rounds and group standings.

## Options

| Name     | Description                  |
| -------- | ---------------------------- |
| `clan`   | Clan tag or name or alias.   |
| `season` | CWL season                   |
| `user`   | Clan by @user mention or ID. |


# /debug

Displays some basic debug information.

Displays some basic debug information.


# /donations

Shows donations and donations received of clan members.

Shows donations and donations received of clan members.

## Options

| Name         | Description                        |
| ------------ | ---------------------------------- |
| `clan`       | Clan tag or name or alias.         |
| `user`       | Donation history of a linked user. |
| `season`     | The season to show donations for.  |
| `start_date` | Starting date (YYYY-MM-DD)         |
| `end_date`   | Ending date (YYYY-MM-DD)           |


# /eval

You can't use it anyway, so why explain?

You can't use it anyway, so why explain?

## Options

| Name    | Description                                                    |
| ------- | -------------------------------------------------------------- |
| `code`  | Code to evaluate.                                              |
| `shard` | Whether to run the code on all shards or just the current one. |
| `depth` | Depth of the returned object.                                  |


# /events

Shows the next in-game events.

Shows the next in-game events.


# /export


# /export attack-log

Export war attack history.

Export war attack history.

## Options

| Name       | Description                                    |
| ---------- | ---------------------------------------------- |
| `clans`    | Clan tags or aliases to filter clans.          |
| `war_type` | Regular or friendly wars (defaults to Regular) |
| `limit`    | Number of wars (Default: 25)                   |


# /export capital

Export clan capital weekends.

Export clan capital weekends.

## Options

| Name    | Description                           |
| ------- | ------------------------------------- |
| `clans` | Clan tags or aliases to filter clans. |


# /export capital-raids

Export capital raid attack stats.

Export capital raid attack stats.

## Options

| Name    | Description                           |
| ------- | ------------------------------------- |
| `clans` | Clan tags or aliases to filter clans. |
| `limit` | Number of raid weekends (Default: 4)  |


# /export clans

Export all linked clans.

Export all linked clans.


# /export cwl

Export CWL stats to Excel.

Export CWL stats to Excel.

## Options

| Name          | Description                               |
| ------------- | ----------------------------------------- |
| `clans`       | Clan tags or aliases to filter clans.     |
| `season`      | Retrieve data since the specified season. |
| `wars`        | Number of wars (Default: 25)              |
| `lineup_only` | Export only the lineup.                   |


# /export last-wars

Export participation history (last played wars)

Export participation history (last played wars)

## Options

| Name       | Description                               |
| ---------- | ----------------------------------------- |
| `clans`    | Clan tags or aliases to filter clans.     |
| `war_type` | Regular or CWL                            |
| `season`   | Retrieve data since the specified season. |
| `limit`    | Number of wars (Default: 25)              |


# /export members

Export a comprehensive version of clan member stats.

Export a comprehensive version of clan member stats.

## Options

| Name             | Description                                                     |
| ---------------- | --------------------------------------------------------------- |
| `clans`          | Clan tags or aliases to filter clans.                           |
| `auto_export_on` | Whether to schedule the export to run every Sunday at 4:55 UTC. |


# /export missed

Export missed attack history.

Export missed attack history.

## Options

| Name       | Description                                         |
| ---------- | --------------------------------------------------- |
| `clans`    | Clan tags or aliases to filter clans.               |
| `war_type` | Regular, CWL or Friendly Wars (defaults to Regular) |
| `season`   | Retrieve data since the specified season.           |
| `limit`    | Number of wars (Default: 25)                        |


# /export rosters

Export all rosters.

Export all rosters.

## Options

| Name       | Description      |
| ---------- | ---------------- |
| `category` | Roster category. |


# /export season

Export comprehensive seasonal stats of clan members.

Export comprehensive seasonal stats of clan members.

## Options

| Name                   | Description                               |
| ---------------------- | ----------------------------------------- |
| `clans`                | Clan tags or aliases to filter clans.     |
| `season`               | Retrieve data since the specified season. |
| `include_past_members` | Include past members of the clan.         |


# /export users

Export Discord members

Export Discord members

## Options

| Name   | Description           |
| ------ | --------------------- |
| `role` | Role to filter users. |


# /export wars

Export War stats to Excel.

Export War stats to Excel.

## Options

| Name         | Description                                         |
| ------------ | --------------------------------------------------- |
| `clans`      | Clan tags or aliases to filter clans.               |
| `war_type`   | Regular, CWL or Friendly Wars (defaults to Regular) |
| `start_date` | Starting date (YYYY-MM-DD)                          |
| `end_date`   | Ending date (YYYY-MM-DD)                            |
| `limit`      | Number of wars (Default: 25)                        |


# /flag


# /flag create

Create a player flag to mark the player as banned or flagged.

Create a player flag to mark the player as banned or flagged.

## Options

| Name               | Description                              |
| ------------------ | ---------------------------------------- |
| `flag_type`        | The type of the flag (ban or strike)     |
| `player`           | The tag of a player to flag.             |
| `reason`           | Reason for the flag.                     |
| `dm_user`          | Whether to DM the user about the flag    |
| `flag_expiry_days` | Flag expiry days (auto deletes the flag) |
| `flag_impact`      | Number of flags this should count as     |


# /flag delete

Delete a player flag.

Delete a player flag.

## Options

| Name        | Description                          |
| ----------- | ------------------------------------ |
| `flag_type` | The type of the flag (ban or strike) |
| `player`    | The tag of a player to delete.       |
| `flag_ref`  | Flag reference of this player.       |
| `clan`      | Clan tag or name or alias.           |


# /flag list

List all player flags.

List all player flags.

## Options

| Name        | Description                           |
| ----------- | ------------------------------------- |
| `flag_type` | The type of the flag (ban or strike)  |
| `player`    | Show all flags against a player       |
| `clans`     | Clan tags or aliases to filter clans. |


# /help

Get a list of commands or info about a specific command.

Get a list of commands or info about a specific command.

## Options

| Name      | Description           |
| --------- | --------------------- |
| `command` | Name of the command.  |
| `ask`     | Find answers with AI. |


# /history

Clan Games, Capital Raids, Donations, and CWL attacks history.

Clan Games, Capital Raids, Donations, and CWL attacks history.

## Options

| Name     | Description                      |
| -------- | -------------------------------- |
| `option` | Select an option                 |
| `clans`  | Select clans for the history.    |
| `player` | Select a player for the history. |
| `user`   | Select a user for the history.   |
| `roster` | Select a roster for the history. |


# /invite

Get the bot invite and support server link.

Get the bot invite and support server link.


# /lastseen

The last seen time and activities of clan members.

The last seen time and activities of clan members.

## Options

| Name   | Description                  |
| ------ | ---------------------------- |
| `clan` | Clan tag or name or alias.   |
| `user` | Clan by @user mention or ID. |


# /layout


# /layout config

Adjust settings related to layout posting and interactions.

Adjust settings related to layout posting and interactions.

## Options

| Name             | Description                                  |
| ---------------- | -------------------------------------------- |
| `allow_voting`   | Enable or disable voting on posted layouts.  |
| `allow_tracking` | Enable or disable tracking of layout copies. |


# /layout post

Post your village layout to showcase it to the community.

Post your village layout to showcase it to the community.

## Options

| Name          | Description                                      |
| ------------- | ------------------------------------------------ |
| `screenshot`  | Upload a screenshot showing your village layout. |
| `layout_link` | Provide a shareable link to your layout.         |
| `notes`       | Add custom notes or details about your layout.   |


# /leaderboard




---

[Next Page](/llms-full.txt/1)