> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeonbot.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Guild Tag

> Reward members who equip your server as their primary guild identity.

Guild Tag allows you to automatically detect when members set your server as their **primary guild** (Discord's Server Identity feature) and reward them with roles. When they switch to another server or remove the tag, the roles are automatically removed.

<Note>
  **Required Permission:** [Admin Access](/permissions/admin-access) or higher — Server Owner, Extra Owner, Trusted User, or Administrator with a role above the bot can use these commands.
</Note>

<Warning>
  **Premium Feature:** This module requires an active Premium subscription. If the server's premium expires, the guild tag system will be automatically disabled.
</Warning>

## Setting Up

Follow these steps to configure the guild tag system for your server.

<Steps>
  <Step title="Run the Setup Command">
    Provide the award role(s), the log channel, and an optional reward message.

    ```bash theme={null}
    .guildtag setup @Repper #tag-log Thanks for repping us, {user}!
    ```
  </Step>

  <Step title="Verify the Configuration">
    Use the show command to confirm everything is set correctly.

    ```bash theme={null}
    .guildtag show
    ```
  </Step>

  <Step title="Test It">
    Send a test message to make sure the output looks right.

    ```bash theme={null}
    .guildtag test
    ```
  </Step>
</Steps>

<Warning>
  You can only assign up to **3 award roles**. Roles with dangerous permissions (Administrator, Manage Server, etc.) are blocked and cannot be used as award roles.
</Warning>

***

## Commands

### Configuration

| Command                       | Description                              |
| :---------------------------- | :--------------------------------------- |
| `.guildtag channel <channel>` | Updates the log channel for tag messages |
| `.guildtag message <text>`    | Sets the reward message                  |
| `.guildtag show`              | Shows the current configuration          |
| `.guildtag reset`             | Deletes the entire configuration         |

### Role Management

| Command                        | Description                |
| :----------------------------- | :------------------------- |
| `.guildtag role add <role>`    | Adds an award role (max 3) |
| `.guildtag role remove <role>` | Removes an award role      |

### Controls

| Command             | Description                                             |
| :------------------ | :------------------------------------------------------ |
| `.guildtag enable`  | Enables the guild tag system                            |
| `.guildtag disable` | Disables the guild tag system                           |
| `.guildtag test`    | Sends a test tag message to the configured channel      |
| `.guildtag sync`    | Manually syncs tag roles for all members (60s cooldown) |

***

## Customizing Messages

The tag message is fully customizable and supports both **dynamic variables** and **custom embeds**. When a member equips your server as their primary guild, the bot sends the configured message to the log channel with all variables parsed into real data.

### Using Variables

You can dynamically insert information like the user's name or server details. Refer to the [Variables](/resources/variables) reference for the full list.

**Available contexts:** Server, Channel, User, Author, Target

<CodeGroup>
  ```bash Input theme={null}
  .guildtag message {user} just equipped {servername} as their primary guild!
  ```

  ```text Output theme={null}
  @john_doe just equipped ZEON Official as their primary guild!
  ```
</CodeGroup>

### Using Custom Embeds

Design a rich embed using the interactive embed builder, then attach it to your message with the `{embed:name}` syntax.

<Steps>
  <Step title="Create the Embed">
    ```bash theme={null}
    .embed create tag_card
    ```

    Use the dropdown menu to customize title, description, color, images, and variables.
  </Step>

  <Step title="Attach to Message">
    ```bash theme={null}
    .guildtag message Welcome to the crew, {user}! {embed:tag_card}
    ```
  </Step>
</Steps>

<Note>
  The `{embed:name}` placeholder is invisible in the final output. The bot strips it from the text and attaches the rich embed below the message. Variables placed inside the embed builder will also parse correctly.
</Note>

### Limitations

<Warning>
  * Guild Tag detection relies on Discord's **Server Identity** feature. If a member has not opted into Server Identity, their tag will not be detected.
  * If the configured log channel is deleted, messages will silently fail until a new channel is set.
  * The `.guildtag sync` command has a **60 second cooldown** per server to prevent abuse.
</Warning>