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

# Vanity Roles

> Members who put your invite in their custom status get a role · automatically.

Discord doesn't expose other members' profile bios to bots, so Criminal looks for the invite in the
part it *can* read: the **custom status**.

```text theme={null}
/config toggle vanity enabled:True
/config role   vanity-role @Advertiser
/config channel vanity-channel #vanity
```

## Detection

When a member's custom status changes, Criminal checks it for the configured keyword. If none is set,
the server's own vanity URL (`discord.gg/yourserver`) is used.

| Outcome | Result |
| - | - |
| Keyword appears | Role granted, announcement posted if the cooldown allows |
| Keyword disappears | Role removed |
| Member goes offline | Skipped · status is only read while online |
| Bot was offline during the change | Picked up on the next status change, or a `/vanity rescan` |

## Notes and limits

* The role must sit **below** Criminal's highest role, or `/vanity status` warns you instead of
  failing quietly.
* Announcements are rate-limited per member; the default cooldown is **one hour**, and re-shown
  statuses inside that window update quietly.
* Announcement text accepts an embed script, so the message can be a card rather than a plain line.
* If the module is off, nothing is checked at all · including on rescan.

## Commands

| Command | What it shows |
| - | - |
| `/vanity status` | Whether it's active, the role, the matched text, the announce channel, cooldown and how many members currently qualify |
| `/vanity list` | Everyone currently showing the invite, with when they were last announced |
| `/vanity rescan` | Re-check every online member right now |

`/vanity rescan` needs **Manage Server**, chunks the guild first, and throttles itself (a short pause
every 25 members) so a large server doesn't hit rate limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.