> For the complete documentation index, see [llms.txt](https://docs.voicestats.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voicestats.xyz/dashboard/role-rewards.md).
# Role Rewards
Role Rewards lets a server award Discord roles for tracked voice activity and counted messages. The module is configured from the VoiceStats Dashboard.
## Requirements
VoiceStats needs the **Manage Roles** permission before the module can be enabled. The bot's highest role must also be above every configured reward role in the Discord role hierarchy.
## Configuration
1. Open **Role Rewards** under **Modules** in the dashboard.
2. Add a voice reward with a required duration, or a message reward with a required message count.
3. Optionally select a text channel for reward announcements.
4. Choose how earned roles should be retained.
5. Enable the module and save the settings.
Each reward must use a unique Discord role. Voice durations must be unique among voice rewards, and message counts must be unique among message rewards. Free servers can configure up to **5 total rewards** and Premium servers up to **50 total rewards**. If Premium ends, the first five configured rewards remain available. Roles that members already earned are not removed.
Voice durations are entered as hours and minutes, such as `10 minutes`, `1 hour 30 minutes`, or `100 hours`. Message rewards use a whole message count, such as `100`, `1,000`, or `10,000 messages`.
The announcement channel is optional. Select a text channel when you want VoiceStats to announce newly earned rewards, or use the **X** inside the selector to clear it.
## Role Retention
The dashboard provides two retention modes:
* **Keep every earned role:** Members keep all reward roles they reach.
* **Keep only the highest earned role:** When a member reaches a higher configured reward of the same activity type, VoiceStats grants the new role and removes the lower reward role of that type.
Voice and message rewards are handled as separate groups. A member can therefore keep their highest voice reward and their highest message reward at the same time.
VoiceStats never removes a member's highest earned reward merely because their member or server statistics were reset. It also never performs a backwards downgrade. Lower reward roles are removed only when a new, higher reward is earned while **Keep only the highest earned role** is enabled.
## When Rewards Are Evaluated
Voice rewards are checked after a member leaves a tracked voice channel or moves to another tracked channel. Message rewards are checked as members send counted messages. A member who has already passed a voice milestone receives the reward after their next tracked voice activity.
Activity excluded by the server's bot, member, or channel filters does not count toward rewards.
## Troubleshooting
If a reward is not granted, check the following:
* The module is enabled.
* VoiceStats has **Manage Roles**.
* The reward role is below the bot's highest role and is not managed by another integration.
* The member performed the relevant tracked activity after reaching the milestone.
* The member does not already have that reward role.
If announcements are missing but roles are still granted, verify that the selected text channel exists and VoiceStats can view and send messages in it.
