📊 Leaderboard

Show the group's members ranked by XP.

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

In the webapp

Open your workspace, select the Telegram group under Channels in the sidebar, then select Gamification, then the Leaderboard tab. Changes save with the Save bar at the bottom of the page.

In Telegram (bot menu)

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