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

# Vanity Tracking

> Monitor and respond to vanity URL usage in your server

## Overview

Vanity tracking monitors when members use your custom vanity URL in status. When detected, the bot can automatically send custom messages, embeds, give roles, and log the activity. Perfect for tracking referrals, monitoring vanity usage, and rewarding members who promote your server.

<Warning>
  **Requires Aurelia Bot**

  Vanity tracking is handled by **Aurelia**, an extension bot of Celestia. Aurelia can only be invited to servers where Celestia is present and vanity features are unlocked.

  [Invite Aurelia](https://discord.com/oauth2/authorize?client_id=1469266577009414326)
</Warning>

<Info>
  Aurelia is built to manage vanity systems independently for improved stability and performance.
</Info>

***

## Setup Requirements

<Steps>
  <Step title="Have Celestia in Your Server">
    Celestia must already be in your server with vanity features unlocked.
  </Step>

  <Step title="Invite Aurelia">
    Invite Aurelia using the link above. It can only join servers where Celestia is present.
  </Step>

  <Step title="Configure Vanity Tracking">
    Use `/vanity` commands to set up your tracking preferences.
  </Step>
</Steps>

***

## Commands

<AccordionGroup>
  <Accordion title="/vanity set" icon="link">
    Set the vanity URL to track.

    <CodeGroup>
      ```bash Syntax theme={null}
      /vanity set url:<vanity_code>
      ```

      ```bash Example theme={null}
      /vanity set url:myserver
      /vanity set url:cool-community
      ```
    </CodeGroup>

    **Parameters:**

    * **url** — Your vanity URL code (without discord.gg/)

    **What It Does:**

    * Monitors statuses for this vanity URL
    * Triggers configured actions when detected
    * Case-insensitive matching

    **Permissions:** Manage Server
  </Accordion>

  <Accordion title="/vanity message" icon="message">
    Set a custom message to send when vanity is detected.

    <CodeGroup>
      ```bash Syntax theme={null}
      /vanity message text:<message> channel:<#channel>
      ```

      ```bash Example theme={null}
      /vanity message text:Thanks {user.mention} for repping our vanity! channel:#general
      /vanity message text:Someone used {vanity}! channel:#promotions
      ```
    </CodeGroup>

    **Parameters:**

    * **text** — Custom message (supports variables)
    * **channel** — Channel to send the message in

    **Available Variables:**

    * `{user.mention}` — Mentions the user who posted the vanity
    * `{vanity}` — The vanity URL that was detected
    * All standard variables from the Variables guide

    **Permissions:** Manage Server
  </Accordion>

  <Accordion title="/vanity embed" icon="code">
    Send a saved embed when vanity is detected.

    <CodeGroup>
      ```bash Syntax theme={null}
      /vanity embed name:<embed_name> channel:<#channel>
      ```

      ```bash Example theme={null}
      /vanity embed name:vanity-thanks channel:#promotions
      /vanity embed name:referral-reward channel:#logs
      ```
    </CodeGroup>

    **Parameters:**

    * **name** — Name of your saved embed (from `/embed builder`)
    * **channel** — Channel to send the embed in

    **Note:** The embed must be saved to your account first using `/embed builder`

    **Permissions:** Manage Server
  </Accordion>

  <Accordion title="/vanity webhook" icon="webhook">
    Send an embed through a webhook when vanity is detected.

    <CodeGroup>
      ```bash Syntax theme={null}
      /vanity webhook webhook_url:<url> embed_name:<name> [username:<name>] [avatar_url:<url>]
      ```

      ```bash Example theme={null}
      /vanity webhook webhook_url:https://discord.com/api/webhooks/... embed_name:vanity-alert
      /vanity webhook webhook_url:https://... embed_name:promo username:Promo Bot avatar_url:https://...
      ```
    </CodeGroup>

    **Parameters:**

    * **webhook\_url** — Discord webhook URL
    * **embed\_name** — Name of your saved embed
    * **username** — Optional: Custom webhook username
    * **avatar\_url** — Optional: Custom webhook avatar

    **Use Cases:**

    * Send to specific channels without bot message
    * Custom branding with webhook username/avatar
    * Professional appearance

    **Permissions:** Manage Server
  </Accordion>

  <Accordion title="/vanity log" icon="clipboard">
    Set a channel to log all vanity detections.

    <CodeGroup>
      ```bash Syntax theme={null}
      /vanity log channel:<#channel>
      ```

      ```bash Example theme={null}
      /vanity log channel:#vanity-logs
      /vanity log channel:#mod-logs
      ```
    </CodeGroup>

    **Parameters:**

    * **channel** — Channel to send logs to

    **What It Logs:**

    * Who repped the vanity
    * When it was repped

    **Permissions:** Manage Server
  </Accordion>

  <Accordion title="/vanity role" icon="user-plus">
    Give a role when vanity is detected.

    <CodeGroup>
      ```bash Syntax theme={null}
      /vanity role role:<@role>
      ```

      ```bash Example theme={null}
      /vanity role role:@Promoter
      /vanity role role:@Referrer
      ```
    </CodeGroup>

    **Parameters:**

    * **role** — Role to assign

    **What It Does:**

    * Automatically gives the role to users who rep the vanity
    * Perfect for tracking promoters
    * Rewarding members who share the server

    **Requirements:**

    * Bot must have Manage Roles permission
    * Role must be lower than bot's highest role
    * Role cannot be managed by integrations

    **Permissions:** Manage Server
  </Accordion>

  <Accordion title="/vanity view" icon="eye">
    View current vanity tracking configuration.

    <CodeGroup>
      ```bash Syntax theme={null}
      /vanity view
      ```

      ```bash Example theme={null}
      /vanity view
      ```
    </CodeGroup>

    **What It Shows:**

    * Currently tracked vanity URL
    * Configured message/embed settings
    * Webhook configuration (if set)
    * Log channel (if set)
    * Role assignment (if set)

    **Permissions:** Manage Server
  </Accordion>

  <Accordion title="/vanity reset" icon="rotate-left">
    Reset all vanity tracking settings.

    <CodeGroup>
      ```bash Syntax theme={null}
      /vanity reset
      ```

      ```bash Example theme={null}
      /vanity reset
      ```
    </CodeGroup>

    **What It Does:**

    * Clears vanity URL tracking
    * Removes all configured actions
    * Deletes all settings
    * Cannot be undone

    <Warning>
      This removes all vanity configuration for your server.
    </Warning>

    **Permissions:** Manage Server
  </Accordion>
</AccordionGroup>

***

## How It Works

<Steps>
  <Step title="Set Your Vanity URL">
    Configure which vanity URL to track:

    ```bash theme={null}
    /vanity set url:myserver
    ```
  </Step>

  <Step title="Configure Actions">
    Choose what happens when vanity is detected:

    ```bash theme={null}
    # Send a message
    /vanity message text:Thanks {user.mention}! channel:#promotions

    # Give a role
    /vanity role role:@Promoter

    # Log activity
    /vanity log channel:#logs
    ```
  </Step>
</Steps>

***

## Configuration Options

You can combine multiple actions:

<CardGroup cols={2}>
  <Card title="Message" icon="message">
    Send a custom thank you message with variables
  </Card>

  <Card title="Embed" icon="code">
    Send a saved embed to a specific channel
  </Card>

  <Card title="Webhook" icon="webhook">
    Send embed through webhook with custom branding
  </Card>

  <Card title="Role" icon="user-plus">
    Automatically assign a role to the user
  </Card>

  <Card title="Log" icon="clipboard">
    Log all vanity detections to a channel
  </Card>
</CardGroup>

***

## Permission Requirements

<CardGroup cols={2}>
  <Card title="Aurelia Permissions" icon="robot">
    The bot needs:

    * Read Messages
    * Send Messages
    * Embed Links
    * Manage Roles (for role assignment)
    * Manage Webhooks (for webhook feature)
  </Card>

  <Card title="User Permissions" icon="user">
    Command Requirements:

    * **Manage Server** — All vanity commands
  </Card>
</CardGroup>

***

## Usage Examples

<Tabs>
  <Tab title="Basic Setup">
    ```bash theme={null}
    # Set vanity URL
    /vanity set url:myserver

    # Send message when detected
    /vanity message text:Thanks {user.mention} for sharing! channel:#general

    # View configuration
    /vanity view
    ```
  </Tab>

  <Tab title="With Role Reward">
    ```bash theme={null}
    # Set vanity
    /vanity set url:community

    # Give promoter role
    /vanity role role:@Promoter

    # Send thank you
    /vanity message text:Thanks for promoting! You've been given the Promoter role. channel:#promotions
    ```
  </Tab>

  <Tab title="With Logging">
    ```bash theme={null}
    # Set vanity
    /vanity set url:myserver

    # Configure logging
    /vanity log channel:#mod-logs

    # Send embed
    /vanity embed name:vanity-detected channel:#promotions
    ```
  </Tab>

  <Tab title="Professional Webhook">
    ```bash theme={null}
    # Set vanity
    /vanity set url:official

    # Configure webhook
    /vanity webhook webhook_url:https://discord.com/api/webhooks/... embed_name:promo-alert username:Promotion Tracker avatar_url:https://...

    # Add logging
    /vanity log channel:#stats
    ```
  </Tab>

  <Tab title="Complete Setup">
    ```bash theme={null}
    # Set vanity
    /vanity set url:epicserver

    # Message + role
    /vanity message text:Thanks {user.mention} for sharing {vanity}! channel:#thanks
    /vanity role role:@Ambassador

    # Logging
    /vanity log channel:#vanity-logs

    # Check config
    /vanity view
    ```
  </Tab>
</Tabs>

***

## Common Use Cases

<AccordionGroup>
  <Accordion title="Referral tracking" icon="link">
    ```bash theme={null}
    /vanity set url:myserver
    /vanity role role:@Referrer
    /vanity log channel:#referral-logs
    ```

    Track who's sharing your server and reward them.
  </Accordion>

  <Accordion title="Promotion rewards" icon="gift">
    ```bash theme={null}
    /vanity set url:community
    /vanity role role:@Promoter
    /vanity message text:Thanks {user.mention}! You earned the Promoter role! channel:#rewards
    ```

    Automatically reward members who promote your server.
  </Accordion>

  <Accordion title="Analytics & logging" icon="chart-line">
    ```bash theme={null}
    /vanity set url:myserver
    /vanity log channel:#analytics
    /vanity embed name:vanity-stats channel:#stats
    ```

    Track vanity usage for analytics.
  </Accordion>

  <Accordion title="Professional branding" icon="sparkles">
    ```bash theme={null}
    /vanity set url:official
    /vanity webhook webhook_url:https://... embed_name:branded-alert username:Server Bot avatar_url:https://...
    ```

    Use webhooks for custom branding.
  </Accordion>
</AccordionGroup>

***

## Tips & Best Practices

<Info>
  **Setup Tips**

  * Test with a test channel first
  * Use variables in messages for personalization
  * Create professional embeds for vanity alerts
  * Set up logging to track usage
  * Consider role rewards for promotion incentives
</Info>

<Note>
  **Message Variables**

  Use these in your custom messages:

  * `{user.mention}` — Tag the user
  * `{vanity}` — Show which vanity was detected
  * `{guild.name}` — Server name
  * `{channel}` — Channel where it was posted
</Note>

<Warning>
  **Important Notes**

  * Aurelia must be in your server (requires Celestia)
  * Vanity features must be unlocked in Celestia
  * Only one vanity URL can be tracked per server
  * Embeds must be saved to your account first
  * Webhook embeds and regular embeds are mutually exclusive
</Warning>

***

## Troubleshooting

### Vanity Not Being Detected

1. Verify Aurelia bot is in your server
2. Check vanity URL is set correctly with `/vanity view`
3. Ensure Aurelia has Read Messages permission
4. Test by posting the vanity URL yourself
5. Vanity matching is case-insensitive

### Role Not Being Assigned

1. Check bot has **Manage Roles** permission
2. Verify bot's role is **higher** than the role being assigned
3. Ensure role isn't managed by an integration
4. Check `/vanity view` shows correct role

### Embed Not Sending

1. Verify embed exists with `/embed list`
2. Check you're the owner of the embed
3. Ensure Aurelia has Send Messages + Embed Links permissions
4. Try using `/vanity message` instead as a test

### Webhook Not Working

1. Verify webhook URL is valid
2. Check webhook hasn't been deleted
3. Ensure embed is saved to your account
4. Test webhook in Discord's webhook settings

***

## Aurelia vs Celestia

<CardGroup cols={2}>
  <Card title="Celestia" icon="star">
    Main bot with all core features:

    * Moderation
    * VoiceMaster
    * Giveaways
    * Embeds
    * And more
  </Card>

  <Card title="Aurelia" icon="link">
    Extension bot for vanity:

    * Vanity tracking only
    * Requires Celestia
    * Better performance
    * Dedicated stability
  </Card>
</CardGroup>

***

## Related Features

<CardGroup cols={2}>
  <Card title="Embed Builder" icon="code" href="/embed-builder">
    Create embeds for vanity alerts
  </Card>

  <Card title="Variables" icon="brackets-curly" href="/variables">
    Use dynamic variables in messages
  </Card>

  <Card title="Auto Responders" icon="reply" href="/auto-responders">
    Automated message responses
  </Card>

  <Card title="Role Management" icon="user-gear" href="/role">
    Create roles for vanity rewards
  </Card>
</CardGroup>