Configuration

Understand the basic configuration used by the bot here.

RankBot uses a fairly simple YAML configuration stored in files, one file per guild using the bot. To edit that configuration, you can use the integrated page within the SajuukBot dashboard to do so.

Managing the configuration requires you to either be the guild owner or have the Manage RankBot user right.

Sample Configuration

Please find below the basic configuration that gets created when the bot is added to a server that hasn't used it before:

---
nickname: ""
ranks:
  1:
    role: 0
    requirement: 10
    notifications:
      enabled: false
      channel: 0
      rich embed: false
      message: "{} has reached Rank 1!"
    decay:
      enabled: false
      time: 0
      period: "week"
rate limits: 
  enabled: false
  limit: 5
  limit seconds: 30
  rate limited length: 60
leaderboard:
  channel: 0
  daily:
    enabled: false
    limit: 15
  weekly:
    enabled: false
    limit: 10
exclusions:
  roles:
  channels:
  categories:
settings:
  modlogs: 0
  mod roles:
  exclude mods: false
  reset statistics: false
  replace roles: true
  role decay: false

Explanation

Nickname

Use this option to set a nickname for the bot. If the nickname in the guild doesn't match this value, the nickname will be automatically updated to match it. The maximum length of a nickname is 32 characters as per the Discord API limitation.

Ranks

Ranks is where the main power of the bot comes from. Under this configuration setting can be a limitless number of rank definitions. Each rank definition is separated by a number in sequential order in the format given above.

The following settings are required for any ranks you define.

Config Name	Description	Type
role	The role that will be granted to the user when they hit the requirement post count. Must represent a valid role that the bot is able to add. Be aware that if a user has a "mod role" defined in the settings, they will have their rank updated, but not gain the role.	Integer
requirement	The required number of messages the user needs to send to get the role defined above.	Integer

Notifications

The notifications group is optional, which means you don't have to set up a notification on a rank if its not wanted. However, if you configure a rank to have notifications, all of the below settings must be defined!

When a user achieves a rank, there is the option to have the bot announce that rank in a defined channel. The following options are available:

Config Name	Description	Type
enabled	Toggles the notification state. If disabled, no notification is triggered in chat, meaning the user gets the role silently.	Boolean
channel	A channel ID for where the notification of this rank being achieved will be posted. Must be a valid channel that the bot can see and post a message in.	Integer
rich embed	Toggles whether the notification message is parsed into a rich embed. Regardless of this setting, the message is also sent in plain text, the rich embed just has some fancier output.	Boolean
message	The message that will be sent when the user achieves this rank. Due to the way this is internally handled, there must be a {} somewhere in the string or the bot will not be able to parse a user mention of who reached this rank.	String

Decay

The decay group is optional, which means you don't have to set up a rank to have an automatic "decay" after a period of time if the rank should not be removed from a user automatically. However, if you configure a rank to decay automatically, all of the below settings must be defined!

In a lot of cases, you might not want specific ranks to be "permanent". For example, the first rank might be one that you want to remove if the user ceases to be active in the community, or you may simply want to make it so that any rank is removed after inactivity. Decay allows you to configure a rank to be automatically removed if a specific time period has elapsed without any other posts by the user. The following options are available:

Config Name	Description	Type
enabled	Toggles whether the rank is automatically removed. If false, or this section is omitted, the rank is permanent and is only removable by manual methods.	Boolean
time	The amount of time that needs to pass to remove the role from a user. The value you put here is entirely dependent on the "time period" defined in the next setting: eg if the period is defined as "week", then this setting represents time in "weeks".	Integer
period	The time gap that time represents. This largely determines the amount of inactivity a user needs to lose a role. Valid options are: week day hour and second	String

Rate Limits

You can choose not to enable the rate limit system by omitting this section from your config. However, if you do choose to include this section, all settings must be defined!

So your server is active... too active, and members race through your ranks like it is nothing. Rate limiting allows you a way to control the speed at which people can gain ranks by forcibly blocking the internal counter from increasing, thus meaning that ranks are gained at a more reasonable pace.

Config Name	Description	Type
enabled	Toggles the rate limit system. If false, there are no limits imposed on gaining ranks.	Boolean
limit	The amount of messages that need to be sent to rate limit a user.	Integer
limit seconds	The amount of seconds that the limit needs to be triggered within, in order to rate limit a user.	Integer
rate limited length	The amount of seconds that a user is rate limited for. During this period of time, a user is not prohibited from posting, but none of the messages they send will increase the internal counter, until that time has expired.

Leaderboard

You can choose not to enable the leaderboards by omitting this section from your config. However, if you do choose to include this section, all settings must be defined!

The leaderboard allows you to give a sense of "achievement" to members who are regularly active in your community. Two leaderboards are available: a daily leaderboard, which updates every day representing the activity of the server since 24 hours ago, and a weekly leaderboard, which updates every Monday representing activity since the previous Monday.

Config Name	Description
channel	Sets the channel where leaderboard messages will be sent. Both daily and weekly will use this value.
daily	Contains the settings for the daily leaderboard. enabled will toggle this leaderboard on or off, and limit will determine the number of members to show. The maximum number of users who can be shown here is 15.
weekly	Contains the settings for the weekly leaderboard. enabled will toggle this leaderboard on or off, and limit will determine the number of members to show. The maximum number of users who can be shown here is 15.

Exclusions

All of the following settings are optional.

You might want to exclude roles, channels or categories from being able to rank up. This might be because the role is representing bots, or the channels/categories represent areas of artificial contributions, such as locations to spam bots or talk to members in a voice channel while not having a microphone. All 3 options here are lists:

Config Name	Description
roles	A list of role IDs which won't rank up. Users who have any of the defined roles will not increment their internal counter
channels	A list of channel IDs which won't rank up. Users who post messages to any of the channels defined here will not increment their internal counter.
categories	A list of category IDs which won't rank up. Users who post into channels that are attached to a category defined here will not increment their internal counter.

Settings

All of the settings below are required.

This section largely covers non-specific settings or toggles to control other settings.

Config Name	Description	Type
modlogs	A channel ID where certain logs of "commands" being triggered should be logged. This must be a channel the bot can read and send messages in.	Integer
mod roles	A list of role IDs representing moderator or administrator roles. Users with any of the roles defined here are able to use commands that require permission to use.	List
reset statistics	Toggles whether a users' ranking data (internal count and rank) should be reset to zero if they leave the server. If false, their data is left intact, otherwise it will be reset to 0	Boolean
replace roles	Toggles whether the next rank that a user gains should replace the one they are moving from. If false, ranks are stacking and the previous one remains on the users' profile.	Boolean
role decay	Toggles whether the role decay system is enabled on any ranks. This must be enabled for any "decay" settings defined in a rank to function, otherwise this feature is unavailable.	Boolean