Permissions

Permissions are quick and easy ways to restrict commands to specific users. The Ralsei Bot permission system works on a slightly complicated syntax, although it isn't that hard to understand. You might be able to relate the syntax to a system like JavaScript's template syntax - if you know what that is.

You can use permissions in the event that you want to lock certain activity to a set number of users on your server. For example, if you wish to only allow the "Moderator" role to automatically delete messages when starting with a -, you can absolutely do so using the permission system.

In the event that you accidentally lock everyone out of a command, don't worry, as administrators have the ability to run any command regardless of their role or permissions.

The Permission String

The permission string is the "serialized" (i.e. put into text instead of logic) version of a set of requirements in order to run a given command. Think of it as a set of conditions which are laid out as a readable line of text.

Let's use the example in the introduction first. The goal was to:

For the permission string, you don't need to consider the event. So let's strike that out.

This demonstrates the purpose of a permission string: it specifies the allowed roles, users, or permissions.

Roles

Roles can be specified either by ID or name. The ID method is preferred as this takes into consideration changes in the name of a role.

Let's take the example from a few paragraphs ago. We'll be looking for a role named "Moderator" for this section. Let's assume that the "Moderator" role has the ID of 12345 (in reality, role IDs can be around 21 numbers long). To target the role using its ID, the following should be used.

To target any role named "Moderator", it must first be converted into Base64, in order to account for all Unicode characters. For a Base64 encoder, visit https://www.base64encode.org/. In this case, "Moderator" is equivalent to TW9kZXJhdG9y. Thus, the following should be used.

Notice the presence of quotes when specifying a name. These quotes are required if you wish to use a name instead of an ID. Without the quotes, the bot will attempt to look for a role with the ID of "Moderator", which would be impossible.

You can require the user to have a combination of roles using a comma separator between each role ID or name. Note that you cannot combine IDs and names in one check. The following will allow both "Moderator" users and "Administrator" users.

Also note the lack of a space. Do not add a space, as this is incorrect syntax – and a waste of space. The format is similar when using IDs.

If the provided role does not exist, everyone will not be able to run the command.

Permissions

You can also target users with a given Discord permission. This is much more straightforward, as you just have to put in the permission code. A full list of which is provided below for convenience, along with what those permissions normally allow in Discord.

Assuming that you want anyone with the "Manage Messages" role to run something, use the following.

Unlike the definition for roles, permissions cannot be combined together. This means that you can only target a specific permission and nothing else.

Users

You can target specific users either by their ID or by their tag. This works much like the definition for roles, and can also be combined, unlike definitions for permissions.

Assuming that the user @chlod has a discriminator of 9493 and an ID of 137832560305766400, you can target them by using any of the following.

"chlod#9493" in Base64 is Y2hsb2QjOTQ5Mw==. Thus, the following is used.

For a Base64 encoder, visit https://www.base64encode.org/.

These can also be combined. Assuming you also want to include the user @Ralsei who has a discriminator of 1055 and an ID of 513534023172227073, you can use the following.

Wildcard

The asterisk (*) is used to represent "any user". In case you want all users to run a command, you can simply set the permission to *.

Negation

All of the previous parts can be negated using an exclamation mark (!) at the start of the permission string. This will cause the bot to interpret anything but the given condition.

For example, to include all users except for @chlod in the previous example, you can use the following.

In that case, all users except @chlod will be able to run the command.

OR

The permission string uses pipes or vertical bars (|) in order to chain two conditions together. This will allow a user to run a command if either of the given conditions are satisfied.

Assuming that the user @chlod in the previous example was a member of the role with an ID of 12345, the following will still allow them to run the command.

This is because the user was given explicit permission. If we change the ID of the allowed user to 513534023172227073, it will no longer work for @chlod.

Permission Keys

The bot allows many things to be restricted behind certain permissions – not just commands. The "key" in this case refers to the ID or code used to identify a certain command, action, quick response, or ability.

Commands

Any command can be restricted using the ID of the command as part of the key. For example, the !ralsei hello command has the ID of greeting. To build its key, simple add a cmd- to the start of the ID. The result of will be the command's permission key.

You can also get a command's permission key using the !ralsei help command, as long as you specify the command you're trying to get the key for. By default, commands fall back to the default permission (detailed below), except for the !ralsei leave command, which requires "Manage Server" permissions.

Abilities

There are two messaging abilities for the Ralsei Bot: use and autodelete. These two restrict a user's ability to use the bot and to autodelete messages, respectively.

These two abilities have the prefix msg-. Thus, the two have the following IDs, respectively.

By default, these are both set to allow all users (*).

Configuration

Configuration values also have their own permissions, and a user must match a permission string for a given configuration value in order to change or display it. A full list of keys is provided below.

Quick Responses

Quick responses have their own permissions as well. The keys for quick responses compose of qr- and the quick response's keyword. For example, given the quick response "honey", one can restrict the usage of a quick response with the following key.

Default

The default permission is used for all commands which do not have a set permission. By default, this is set to all users (*). The difference of the default permission with the msg-use key is that the default permission applies only to commands that do not have set permission strings, whereas msg-use restricts bot usage only to those who match it, regardless if they can run a command or not.

Issues

Like all bots, the Ralsei Bot can sometimes get things wrong and incorrectly parse a permission string. In such cases, please report them to use using !ralsei report or through the support server.