Skip to main content
The reputation system awards XP to members for sending messages. Enough XP earns a new level, and specific levels can automatically assign role rewards. A cooldown prevents spam farming, and a leaderboard tracks the most active members.

​
Configuration

config.json
{
  "reputation": {
    "enabled": false,
    "xpPerMessage": [5, 15],
    "xpCooldownSeconds": 60,
    "announceChannelId": null,
    "levelThresholds": [100, 300, 600, 1000, 1500, 2500, 4000, 6000, 8500, 12000],
    "roleRewards": {}
  }
}
Set enabled to true to activate the system.

​
How XP is awarded

Every non-bot message in a guild channel runs through the XP handler:
  1. The feature gate checks reputation.enabled.
  2. Messages shorter than 10 characters are skipped (anti-spam).
  3. The handler checks the in-memory cooldown map. If the user earned XP within the last xpCooldownSeconds seconds (default: 60), the message is skipped.
  4. A random XP amount between the two values in xpPerMessage (inclusive) is awarded.
  5. The user’s total XP is upserted into the reputation table.
  6. The cooldown timestamp is set.
Example: award between 5 and 15 XP per message
{
  "reputation": {
    "xpPerMessage": [5, 15],
    "xpCooldownSeconds": 60
  }
}
The cooldown is per-user per-guild and stored in memory. It resets on bot restart, but the XP totals in PostgreSQL are persistent.

​
Levels

Levels are determined by comparing total XP against the levelThresholds array. The index in the array corresponds to the level (index 0 = level 1, index 1 = level 2, etc.).

​
Default thresholds

LevelXP required
1100
2300
3600
41,000
51,500
62,500
74,000
86,000
98,500
1012,000
You can define as many levels as you like by extending the array.

​
Level-up announcements

When a member levels up, the bot sends an embed to announceChannelId if one is configured:
config.json
{
  "reputation": {
    "announceChannelId": "111222333444555666"
  }
}
The embed shows the member’s mention, new level, total XP, and a trophy icon if a role reward was assigned.

​
Role rewards

Map specific levels to role IDs under roleRewards. When a member reaches that level, the bot automatically assigns the role.
config.json
{
  "reputation": {
    "roleRewards": {
      "3": "111222333444555666",
      "5": "222333444555666777",
      "10": "333444555666777888"
    }
  }
}
Keys are level numbers as strings. If the bot cannot assign a role (e.g. the role is above the bot’s highest role), it logs the error and continues — the level-up announcement still fires.
The bot’s role must be positioned above any reward role in Server Settings → Roles. Role assignment errors are logged but do not block the level-up announcement.

​
Commands

Shows your current XP, level, and a progress bar toward the next level.
Example output
▓▓▓▓▓▓░░░░ 60%
Level 4 • 1,234 XP
Available to everyone. No options required.
Shows the top members ranked by XP for the current server.Available to everyone. No options required.

​
Progress bar format

The /rank command renders a 10-segment progress bar using block characters: 
▓▓▓▓▓░░░░░ 50%
▓ segments represent progress toward the next level. The percentage is rounded to the nearest whole number.

Build docs developers (and LLMs) love

Get started for freeTalk to us