The Privilege System

Botpy has an inbuilt privilege system to allow only trusted users to run certain commands, and to keep your bot safe and secure at all times.

System Design

Botpy’s privilege system can have an unlimited number of privilege levels. Each level is associated with a number which tells us how much power each level has. By default, there are no privilege levels, and therefore each command of the bot can be run by anyone.

For example, a bot can have two privilege levels:

Level Name	Grant Level
regular user	1
owner	2

Each user is associated with a privilege level. A user does not have a privilege level till assigned one. In other words, by default, every user’s grant level is 0. All users who have a privilege level can be listed using the default membership command (code reference here).

Each command has a minimum grant level, which can be configured as you wish (see commands section for more information). So, if a command’s minimum grant level is set to 1, but the user running the command has no privilege level (or one with the grant level lower than 1), the command will not run. For a command to be executed, the command’s privilege level needs to be lesser than or equal to the user’s grant level.

A user’s privileges can be changed by using the

Warning

Setting a command’s grant level higher than the maximum grant level of the privilege levels will render the command unusable, even for users with the highest privileges.

Note

User privileges are room based. This means that a user with privileges or an RO with privileges in one room will not have privileges in another unless added.

Now, let’s see how to implement the above described system through Botpy.

Adding a privilege level

A function named add_privilege_type (github reference here) which is a part of the Bot class is defined as follows:

add_privilege_type(self, privilege_level, privilege_name)

The first (excluding self) argument privilege_level is an integer containing the grant level. The second argument, privilege_name contains the name of the privilege level.

Example code to implement two privilege levels follows.

bot.add_privilege_type(1, "regular_user")
bot.add_privilege_type(2, "owner")

The two privilege types have now been added!

Note

Add privilege levels only after the bot has started.

Granting all room owners maximum privileges

Often, granting all room owners (ROs) of a room privileges makes sense. Now, instead of manually adding all ROs to the privilege list, Botpy provides a function to privilege all ROs, which is defined as follows:

set_room_owner_privs_max(self, ids=[])

The function set_room_owner_privs_max (reference here) will grant all ROs maximum privileges. By default, it does this for all rooms the bot runs in. If you want ROs to have privileges in specific rooms only, specify the room ids in the second argument, ids.

The following

bot.set_room_owner_privs_max()

will grant maximum privileges to all ROs in all rooms the bot is in!

Warning

Once this has been run, ROs in these rooms will have the privileges forever. Simply deleting this line from the bot’s code will not revert this. Their privileges will have to be manually removed through bot commands.