Levels and XP

The system is off on a new server. Turn it on with the Enable levels switch on the Levels page of the website, or with the Enable button in the Leveling category of /config (see Bot configuration).

When you turn it on:

• members start earning XP;
• the /rank, /modify-xp and /reset-levels commands appear on the server.

When you turn it off, XP stops increasing, those three commands disappear and running giveaways that award XP are cancelled. XP already earned is kept.

Every message sent in a channel of the server can earn XP: text channels, threads, forum posts and the chat of voice channels. Direct messages don't count. No channel or role is excluded.

For each message, the bot applies these rules in order:

1. System on: if levels are turned off, nothing is counted.
2. Who: bots, system messages and members blacklisted from Dispatch.IO earn nothing. Neither does a message blocked by the anti-raid.
3. 2-second delay: after a message, about 2 seconds must pass before a new message earns XP. The delay restarts with every message, even one that earned nothing.
4. Content: the bot removes mentions (members, roles, @everyone, @here), links and Unicode emojis (😀) from the text. If nothing is left, the message earns nothing. That is the case for a message made only of emojis, links or mentions, or an image without text.
5. Calculation: the message earns a random whole number of XP between Text XP min and Text XP max (5 and 15 by default, both included).
6. Short message: if the remaining text has fewer than 5 words or fewer than 20 characters, the XP is halved (rounded down).

Examples with the default settings

A member earns XP while connected to a voice channel of the server, temporary voice channels included:

• every 60 seconds spent in voice, they receive the Voice XP (20 by default);
• the first XP arrives after one full minute;
• switching voice channels restarts the counter: the started minute is lost;
• leaving voice stops the counter;
• the voice XP value is the one in place when the member joined voice: if you change it, the change applies from their next connection.

The bot does not check whether the member muted their microphone or headset, nor whether they are alone in the channel. Bots and members blacklisted from Dispatch.IO earn nothing. When the bot restarts, it resumes counting for members already in voice.

The level depends on the member's total XP on the server, that is message XP + voice XP:

level = whole part of √(total XP ÷ 100)

In other words, reaching level N takes 100 × N² total XP, and each level takes a little more than the previous one (100 × (2N + 1) XP between level N and level N + 1).

With the default settings, level 10 is about 1,000 normal messages, or 8 h 20 min in voice. Message XP and voice XP never go below 0.

XP and levels are specific to each server: a member starts from zero on another server.

A level-up is detected when total XP reaches a new threshold after a message, a minute in voice or a giveaway that awards XP (see Polls, giveaways and suggestions). The bot first gives the reward roles, then posts the announcement.

The announcement is posted in the notification channel (Notification channel on the website, Notification Channel in /config), in the server language:

• the text "Congratulations @Alex, you have reached level 12!", which mentions the member;
• the level card;
• a Show Profile button that opens the member's public page on the website (their level card and flame history).

If a role reward exists for this exact level, the text becomes "New role unlocked for @Alex: Niveau 10". The role name is written as plain text: the role itself is not mentioned.

If a member gains several levels at once (for example with an XP giveaway), only one announcement is posted, for the level reached.

The level card

The card (1200 × 400 pixels) shows the member's avatar in a polaroid, the "LEVEL UP" tag, their total XP, the title "WELL DONE!", a progress bar towards the next level (percentage and XP still needed, for example "1,250 XP → LVL 13") and a trophy with the level number.

The background is the first one available among: the member's own level card background (personal plans, set in their website preferences), the server's Level image (website only), the server's welcome image, then the Dispatch.IO default image.

A reward links a role to a level (from 1 to 999, one role per level). It is set on the website (Role rewards) or in /config (Rewards).

At every level-up, the bot goes through all the server's rewards:

• Normal reward: the role is given if the new level is greater than or equal to the reward level. Roles stack: a member at level 20 keeps those of levels 5, 10 and 15. A normal role is never removed automatically, even if the member's XP goes down or is reset.
• Provisional reward (Provisional role, website only): the role is given only when reaching that exact level, then removed as soon as the member reaches a higher level. Example: provisional role at level 26 → given at level 26, removed at level 27.

To give a role, the bot needs Manage Roles and the role must be below the bot's highest role. In /config, roles that are too high or managed by an integration are refused. A role deleted from Discord is skipped.

XP changes made by an administrator (/modify-xp, /reset-levels, Members & XP page) trigger neither an announcement nor role changes. A reset does not remove reward roles already obtained.

Some values cannot be set per server: the 2-second delay between two messages, the short-message threshold (5 words or 20 characters) and the one-minute voice interval.

Premium plans

A server chosen as the Ultimate slot of an Individual Ultimate subscription counts as Ultimate. Without Basic or Ultimate, rewards marked provisional stay saved but behave like normal rewards; they become provisional again on renewal. There is no XP bonus or multiplier. Plan details are on Premium plans and limits.

Learn more: Flames (streaks), the other engagement module, and Permissions and roles.