📊 Leaderboard

Display a leaderboard showcasing the most active users. The leaderboard adds a competitive element by displaying the top-performing users based on XP, encouraging friendly competition and recognizing top contributors.

Overview

Leaderboard provides:

• Competitive Element: Friendly competition drives engagement
• Public Recognition: Top contributors get visible acknowledgment
• Motivation: Members strive to climb rankings
• Transparency: Clear view of community activity
• Automated Updates: Leaderboard refreshes automatically
• Customizable Visibility: Public or private access control

How It Works

The leaderboard tracks and displays members based on their total XP:

1. XP Tracking: System continuously monitors member XP
2. Ranking: Members sorted by total XP (highest first)
3. Display: Top members shown with their XP and level
4. Update: Automatically refreshes at set intervals
5. Access: Members can view via /leaderboard command

Configuration

To access Leaderboard settings:

1. Use the /settings command in your chat
2. Navigate to 🏆 Gamification → 📊 Leaderboard
3. Configure the settings below

Leaderboard Settings

🔄️ Enabled / Disabled

🔄️🟢 Enabled / 🔄️🔴 Disabled: Activate or deactivate the XP leaderboard for this group.

Impact of Disabling

Disabling the leaderboard stops public display and automatic updates but doesn't reset XP or rankings. Data is preserved for when you re-enable it.

Admins: Included / Admins: Excluded

Choose whether admins are included in the leaderboard rankings. Most communities exclude admins to keep competition fair for regular members.

🔓 Visibility

🔓 Visibility: Public / 🔒 Visibility: Private: Allow or restrict the use of /leaderboard by non-admin users.

• Public — any member can type /leaderboard to view current standings
• Private — only admins can trigger the leaderboard display

⏳ Update Interval

Set the interval (in minutes) for automatically posting an updated leaderboard to the group.

👥 Top Users

Choose how many top users are shown in the leaderboard. Controls the length of the rankings list displayed.

💭 Message

Customize the leaderboard message template. The following variables are available:

Variable	Description
{leaderboard}	The ranked list of users
{top_n}	Number of users shown
{total_xp}	Total XP across all listed users
{updated_at}	UTC timestamp of the last update
{title}	Leaderboard title

📊 View Leaderboard

Immediately posts the current leaderboard to the group on demand, independent of the automatic update interval.

Admin Commands

Command	Description
/leaderboard	Display the current XP leaderboard in the chat

Troubleshooting

Leaderboard not displaying?

• Verify leaderboard is enabled (🟢)
• Check bot has posting permissions
• Ensure members have earned some XP
• Test with /leaderboard command

Members can't access /leaderboard?

• Check visibility is set to Public
• Verify bot is responding to commands
• Ensure command isn't blocked by filters
• Test command yourself as admin

Automatic updates not posting?

• Verify update interval is set
• Check bot has posting permissions
• Ensure bot is online and functioning
• Review interval setting

Rankings seem wrong?

• Verify XP is tracking correctly
• Check for manual XP grants that may have occurred
• Ensure XP cooldowns are working
• Review XP earn rates

Admins appearing when excluded?

• Double-check admin exclusion setting
• Verify users are properly set as admins in Telegram
• May need to toggle setting off and on
• Test with fresh leaderboard view

Leaderboard spam concerns?

• Increase update interval (e.g., 120 to 240 minutes)
• Disable automatic updates, use manual only
• Create dedicated leaderboard channel
• Poll community for preferred frequency