What is a Discord bot?
A "bot" on Discord refers to a user-like member of your server that is software that you can use to automate various actions. It's denoted by a "Bot" tag next to its name. Bots use Discord's public "API" to do actions like send messages, modify roles, etc.
"Recorders" & "Front Ends"
In order to make sure your valuable stats are not missed, Statbot runs two parts of the bot separately. You will often hear these referred to as the Recorders and Front-Ends.
- Recorder: The part of the bot that records stats.
- Front-End Bot (abbr: Front-Ends): The part of the bot that responds to commands in Discord, applies Statroles, and edits Statdocks.
This separation means that stats are often still recording even if the bot temporarily stops responding to commands.
Without going into the complicated details, Discord has large bots connect to it over many connections so that it can split events between them. All of the bot's servers (like the one you've added the bot to) are divided amongst these connections. A Shard refers to one of these connections. Typically, a Shard for Statbot will have 1000 or so servers on it.
This is useful to know because sometimes parts of Discord's API or the bot may go offline but that doesn't necessarily mean that the entire bot is down.
Sometimes Discord's API goes offline and is inaccessible. When this happens, bots may be unable to function properly until the issues are resolved on Discord's side. These "API outages" will often be felt by users as well. If the Statbot team detects an outage, generally an announcement will be made in the support server.
How to Use Bot Commands
Commands are the various operations that you can have a bot perform through sending messages in Discord. Statbot's commands primarily focus on displaying stats and configuring settings.
The prefix is the most important part of the command. Bots watch for the prefix (often a setting you can customize) to
know that the message contains a command that it needs to run. In regards to commands, Statbot ignores messages that
don't start with the server's prefix or
Statbot's default prefix is
s? (not case-sensitive). You can also use
@Statbot instead of the prefix which is
helpful if you ever forget your prefix and want to check it in Discord rather than the Dashboard.
Below are some examples of Statbot commands illustrating how a prefix is used:
Setting a custom prefix for your server is covered later in this guide under 5. Common Settings.
The command you want to run will need to immediately follow the prefix. This does not apply to @Statbot.
Statbot has Multipart Commands (multiple-part commands) which are commands that are more than a single word. An
example is the
stats me command. This is only used to categorize commands and you won't be able to use the first word
by itself. If you do, the bot will send a message instructing you of what a valid command will be.
The most common example is the
stats category of commands.
stats top, and
stats members are all
Multipart Commands starting with
stats alone is one such case that the bot will return a message
instructing you that it's a Multipart Command and cannot be ran alone.
The parts in Multipart Commands are different than Parameters which we'll cover next. They change which command is ran rather than change the input into a given command.
Since Multipart Commands can be annoying to type every time, Aliases (discussed below) offer an easier way to use commands.
Commands often accept "Parameters", "arguments", or "options". These terms are interchangeable and just mean that the command accepts additional input immediately following the command.
The most common example is the
help command. It can take a Statbot command as a Parameter so something like
help prefix will return the help information for the
You will often use Parameters to target specific channels, members, or roles. In most cases, commands will accept
names, @ or # mentions, and Discord IDs. You can view valid Parameters with examples for all Statbot commands
help command and in these docs in the commands section.
Parameters are different from Flags which are an advanced topic outside the scope of this guide. After you get comfortable with the bot, we suggest you take a look at flags for extreme customization of the output of various commands.
An Alias is a command that acts as a shortcut or replacement for another. For example, one of the Aliases for
stats messages command is
s?stats messages and
s?m return the same output. Aliases accept the
same Parameters like their full counterparts do. (e.g.
This is particularly useful for lengthy Multipart Commands. For instance, an Alias of the
stats me command is
You can find a list of all the Aliases by running the
help command doesn't accept Aliases as a Parameter.
s?help stats me
Navigating Statbot's Commands
Below you'll find a labelled diagram of different parts of the command structure with what we now know about commands.
Statbot has many simple commands to get you started on your stats journey. Below are 5 common commands that you can use to get familiar with Statbot:
help- Shows a categorized list of all the commands.
user- Shows stats information of a given user including their top message and voice channel and the date they joined the server.
me- A shortcut for
stats user @you. Optionally accepts "messages" and "voice" as Parameters. Supports the Aliases of the
voicecommands as well.
me messages- A shortcut for
stats messages @you. Alias example:
me voice- A shortcut for
stats voice @you. Alias example:
members- Shows information about the member growth of the server including a graph.
counter setup- Creates a set of preset channel counters displaying various stats about the server.
Sometimes commands will change in structure. While we try our best to support backwards compatibility, you should make
it a habit to run the
help command whenever a command you think should work isn't.
Privileged Commands (aka: "Admin Commands") are commands that require the member using the command to have certain
Discord permissions or Role-Based Access Control (RBAC) overrides. By default, members
Manage Server Discord permissions can edit all Statbot settings with the only one
exception controlled by the Elevate Manage Server setting.
When running the
help command, you'll notice a mix of regular and Multipart Commands displayed in categories.
These categories are mostly to group commands together and make it easier to find what you need. Statbot does not use a
module system like some other bots do.
Take care to notice the
* asterisk on categories and individual commands that require the member to have elevated
privileges. These commands will not respond to regular members.
Information on what Discord permissions various features of Statbot require to function properly.
The following Discord permissions are necessary to properly track stats:
- Read Messages: Required on text channels to track sent messages.
- See Channel: Required on voice channels to track voice minutes.
Responding to Commands
The following Discord permissions are necessary to properly respond to commands in Discord. These are all in regards to text channels:
- Send Messages: Required to send any response.
- Embed Links: All commands use tidy embeds which require this permission.
- Attach Files: Many commands send graphs and some can send .csv files.
The following permission is necessary for the Statrole feature:
- Manage Roles: Required to assign and remove roles to/from members.
Statroles rely on stats tracked by the bot and so make sure that the bot has the permissions noted above on the channels you want stats for.
A member's highest role must be higher than the role they're trying to assign. This is true for bots as well. Make sure that Statbot has a role higher than the one you want it to assign. The configurator on the website will show only roles that the bot can assign, but roles are often moved around so keep this in mind.
- Manage Channels: Required server-wide or on the channels created for Statdocks.
- See Channel: Required to edit channels.
- Connect: Required to edit channels (including channel name) requires this permission on the channel.
Finally, because of the importance that Discord places on this item, it is worth highlighting the
toggle userprivacy command. This command allows a user to anonymize their
stats across all servers. This process was explained earlier in the Welcome page's
section about privacy.
Users are sent the following warning before when being asked for confirmation for the action:
We greatly value your privacy. By activating User Privacy, we will anonymize your message and voice data. Users are limited to toggling this setting only once every 24 hours. After toggling User Privacy "On", a process will begin to anonymize all of the aforementioned data. The entire process can take some time to complete and once started, can not be stopped. You will receive a notification on this website letting you know when you have been successfully anonymized.
By anonymizing your data, Statbot may not be able to accurately determine your activity in a server when executing services like Smart Prune and Statroles. Anonymizing your data may result in decreased user experience. If you understand and wish to continue...