Modules

Leveling

Members earn XP for chatting, talking in voice, using commands and reacting. XP adds up to levels, levels can give roles, and everyone can see where they stand with /rank, /leaderboard and a web leaderboard.

Setting it up

1. Open Leveling in the dashboard. It's under Community Tools.
2. Turn it on with the switch at the top right.
3. Pick how members earn XP on the Earning XP tab. Messages are on by default.
4. Press Save Changes. Members start earning straight away.

Earning XP

Each way of earning has its own switch, XP amount and cooldown. The cooldown stops spam: a member earns once, then waits.

Level speed changes all XP at once: Slower halves it and Faster doubles it. The dashboard shows how many messages level 10 takes at your settings. You can also stop some channels or roles from earning, and choose whether members lose their XP when they leave or are banned.

Voice XP limit stops voice XP once a member has earned a set amount from voice per day, per week or per month, for example 5,000 a day and 20,000 a week. Only voice XP counts toward it: messages, commands and reactions are never limited. A new day starts at midnight in the server's time zone. It's free.

Crowd bonus gives more voice XP when more people are in the channel, counting the member but not bots. Set ranges like 3 to 5 people and 6 to 10, or leave the end empty for "or more", and give each a bonus as a percent (+5% of their voice XP) or as XP (+3 XP a minute). It can count in every voice channel or only the ones (or categories) you pick. A bonus limit per day, week or month stops the bonus once a member has earned that much of it; they still get their normal voice XP. Free servers get 2 ranges, Premium 5.

Levels

Each level takes a bit more XP than the one before. With the default message XP (about 20 a message):

Level up message

Sparrow can post a message in a channel you pick when someone levels up. Write it as text, an embed or Components V2, with a live preview. Only the member who levelled up is pinged.

Tick any mix of the last three, like reward levels and the levels you pick. It posts at all of them.

Want a different message when someone gets a role? Open the With a reward role tab above the message and turn it on. Levels that give a reward role post that one, like "{user} is now {role}!", and every other level posts the normal message.

These placeholders work in the message, along with the usual ones like {server}:

Role rewards

Give a role when members reach a level. Choose whether they keep every reward role they've reached or only the highest one, and whether a role is taken away if their level drops (for example after /xp remove). Members who leave and come back get their reward roles back if they still have their XP.

You can also give roles for a number of messages, hours in voice or reactions. Every message and reaction counts, but only once every few seconds per member (5 by default, you pick), so spam doesn't count. Voice time counts every minute with the same rules as voice XP, even if voice XP is off. Free servers get 5 of each, and Premium has no limit.

Added a reward after members already passed it, or imported XP from another bot? Press Update everyone's roles on the Role rewards tab. Sparrow checks every member and gives the reward roles they've earned, and takes away ones they no longer earn if your settings say so. You can do it once every 10 minutes.

Boosters

Roles or channels can earn more XP, like +50% for Server Boosters. Free servers get 3 role boosters and 3 channel boosters, and Premium has no limit. With Stack role boosters on, a member with two booster roles gets both added up. Off, they only get the biggest one. Channel boosters add on top either way.

Voter boost gives members more XP for 12 hours after they vote for Sparrow on top.gg: pick 5% or 10%. It's on by default, adds on top of boosters, and puts a Vote for boost button on /rank. Turning it off needs Premium.

Double XP events

On the XP events tab, plan a time when members earn more XP: 1.5x, 2x (the usual), 3x, or your own number from 1.1x to 5x, from a start to an end time (up to 14 days, in your own time). Each event counts down to when it starts. Pick where it counts (the whole server, all text channels, all voice channels, or channels and categories you pick) and who gets it (only some roles, and never some roles). Sparrow can post in a channel when it starts and when it ends, and /rank mentions it while it runs. If two events run at once, the biggest counts. Without Premium you can have one event at a time, up to 2x. Premium allows 10 at a time and up to 5x.

Activity streaks

Turn on Activity streaks on the Earning XP tab and members build a streak by earning XP every day. You can ask for a minimum amount of XP in a day for it to count. Streaks can give bonus XP (a set percentage for each day after the first, 2% by default, up to a limit you pick, 20% by default), or just show on /rank. Missing a whole day starts it over. Days change at midnight in the time zone you pick (the same one XP decay uses). The rank card on /rank shows a flame badge with the number of days, unless you turn that off. A member's own /rank also says whether today counts yet, or how much more XP they need today to keep their streak. It's free.

Rank card

/rank shows a card with the member's avatar, level, rank and a progress bar to the next level. Pick its colors on the Rank card tab, or use your own background image. The preview there is exactly what members see.

Members can also style their own card: /rank has an Edit your card button that opens a private editor with color menus and custom colors. With Premium they can upload their own background image too. It only changes their card, and Use the server's cardundoes it. You can turn this off with Let members edit their own card on the Rank card tab.

On a server without Premium, members can change their card for 12 hours after they vote for Sparrow on top.gg (/vote). Their card keeps the colors they picked after that, and editing it again needs another vote. With Premium, members can edit their card any time.

Leaderboard

Staff (the owner, and anyone with Administrator or Manage Server) can click a member's name on the web leaderboard to give, remove or set XP, set a level or reset them, with a reason. It works like /xp: reward roles update and it's logged.

The web leaderboard is open to anyone with the link by default. You can make it for server members only (they log in with Discord) or turn it off. Its link uses your server's ID, or a custom name like /leaderboard/your-server with Premium.

Everyone with XP is on the leaderboards by default. With Premium you can hide banned members, members who left, and members who haven't earned XP in 7, 14, 30 or 60 days. Hidden members keep their XP, don't take up a rank, and show again when they come back or earn XP.

XP decay

Members who stop earning XP can slowly lose some. Turn it on in the XP decay tab. It runs once a day at 00:00 in the time zone you pick, and earning any XP stops it straight away.

Members who left the server don't lose XP. It waits for them if they come back.

Import from another bot

Moving from another bot? The Import tab brings your members' levels over. You see who's found before anything changes, and reward roles are given to match. Sparrow keeps its own XP table, and members keep their level.

If someone already has XP in Sparrow, pick what happens: keep the higher, replace it, or add to it. Members who aren't in the server keep their imported XP for when they come back.

To leave quiet members behind, tick Below level, With less XP than, or both, and enter a number. With both, a member below either one isn't imported. Levels and XP are as they'll be in Sparrow, and the preview says how many are left out.

Resetting XP

/xp reset member resets one member, /xp reset role everyone with a role, and /xp reset everyone the whole server. The same is on the dashboard: Reset everyone's XP at the bottom of the Earning XP tab. XP and levels go back to 0, and level reward roles are taken away unless you pick keep_roles.

Resetting a role or everyone shows how many members it hits and asks first. A backup is saved before it runs, and with Premium the Backups tab puts it back. With Logs on, the reset is logged once with who did it and why.

Backups

Sparrow saves a copy of everyone's XP once a day, and before every import or restore. If someone resets members' XP, by mistake or on purpose, open the Backups tab, pick a day and restore it. You see who changes before anything happens.

Backups are a Premium feature. They're kept 30 days, the oldest deleted as new ones are saved. A copy is saved just before every restore too, so a restore can be undone.

Commands

See all commands on the commands page.

Good to know

• Sparrow needs Manage Roles for reward roles, and its role has to be above them.
• Bots never earn XP.
• Levels go up to 1,000. Members keep earning XP after that, so the leaderboard still ranks them.
• Only Administrator, Manage Server or a Sparrow Master Role can use /xp and /level, even if a server shows them to other roles in its Integrations settings.
• /xp and /level also work on members who left or were banned: use their user ID. No roles are changed for them.
• Staff changes with /xp and /level never post a level up message. Add a reason and, with Logs on, every change is logged with who made it.
• If something can't be done, like posting in a deleted channel, the Leveling page shows why.

Free servers & Premium