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

# Vanity Roles

> Automatically reward members who rep your server's vanity URL in their status.

Vanity Roles lets you automatically detect when members add your server's vanity URL to their custom status and reward them with roles. When a member removes the vanity from their status, the roles are automatically taken away.

<Warning>
  Your server **must be Boost Level 3** (or Partnered) to use this feature. Discord only provides custom vanity URLs to servers that have reached Level 3 boosting.
</Warning>

<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 vanity roles system will be automatically disabled.
</Warning>

## Vanity Client Bot

Due to Discord API limitations, the main bot cannot reliably track custom status changes across all members in real time. To solve this, Vanity Roles uses a **separate lightweight bot** (the Vanity Client) that runs alongside ZEON specifically to monitor member statuses.

**You must invite the Vanity Client to your server** for this module to function. It requires no extra permissions beyond reading member presences.

<a href="https://discord.com/oauth2/authorize?client_id=1503291624661323858" target="_blank">
  **→ Invite Vanity Client Bot**
</a>

<Note>
  The Vanity Client is a companion bot that works silently in the background. It does not respond to any commands — all configuration is done through the main bot using the `.vanityrole` commands.
</Note>

***

## Setting Up

Follow these steps to configure vanity roles for your server.

<Steps>
  <Step title="Invite the Vanity Client">
    Use the invite link above to add the Vanity Client bot to your server. Without it, status tracking will not work.
  </Step>

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

    ```bash theme={null}
    .vanityrole setup @Repper #vanity-log Thank you {user} for repping {servername}!
    ```
  </Step>

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

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

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

    ```bash theme={null}
    .vanityrole 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                                 |
| :------------------------------ | :------------------------------------------ |
| `.vanityrole channel <channel>` | Updates the log channel for reward messages |
| `.vanityrole message <text>`    | Sets the reward message                     |
| `.vanityrole show`              | Shows the current configuration             |
| `.vanityrole reset`             | Deletes the entire configuration            |

### Role Management

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

### Controls

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

***

## Customizing Messages

The reward message is fully customizable and supports both **dynamic variables** and **custom embeds**. When a member puts your vanity in their status, 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, server name, or role count. Refer to the [Variables](/resources/variables) reference for the full list.

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

<CodeGroup>
  ```bash Input theme={null}
  .vanityrole message Thank you {user} for repping {servername}! You now have {userrolecount} roles.
  ```

  ```text Output theme={null}
  Thank you @john_doe for repping ZEON Official! You now have 4 roles.
  ```
</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 vanity_card
    ```

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

  <Step title="Attach to Message">
    ```bash theme={null}
    .vanityrole message {user} is now a repper! {embed:vanity_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 (like `{user}` in the title) will also parse correctly.
</Note>

### Limitations

<Warning>
  * The reward message only sends when a member **adds** the vanity to their status, not when it is removed.
  * If the configured log channel is deleted, messages will silently fail until a new channel is set.
  * The `.vanityrole sync` command has a **60 second cooldown** per server to prevent abuse.
</Warning>