How to Use a Discord Bot

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.

"Shard"

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.

info

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.

Prefix

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.

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:

# With default prefix
s?help
s?aliases
s?stats members
s?statdocks setup
# With bot @mention
@Statbot help
@Statbot aliases
@Statbot stats members
@Statbot statdocks setup

Setting a custom prefix for your server is covered later in this guide under 5. Common Settings.

info

The command you want to run will need to immediately follow the prefix. This does not apply to @Statbot.
s? help
s?help
@Statbot help
@Statbothelp

Multipart Commands

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 me, stats top, and stats members are all Multipart Commands starting with stats. Running 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.

Command Parameters

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 prefix command.

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 via the 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.

Aliases

An Alias is a command that acts as a shortcut or replacement for another. For example, one of the Aliases for the stats messages command is m, so s?stats messages and s?m return the same output. Aliases accept the same Parameters like their full counterparts do. (e.g. s?m @User)

This is particularly useful for lengthy Multipart Commands. For instance, an Alias of the stats me command is me.

You can find a list of all the Aliases by running the aliases command.

info

The help command doesn't accept Aliases as a Parameter.
s?help me
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 messages and voice commands as well.
    • me messages - A shortcut for stats messages @you. Alias example: me msg
    • me voice - A shortcut for stats voice @you. Alias example: me v
  • 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.
info

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

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 with the Administrator or 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.

Required Permissions

Information on what Discord permissions various features of Statbot require to function properly.

Tracking

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.

Statroles

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.

Important

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.

Statdocks

  • 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.

User Privacy

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...