Content

Article Overview

Preface: In order to avoid confusion, the Statbot feature “Statrole” this page is about will always be referred to as such and should not be confused with a Discord “role”. These two terms will never be used interchangeably.
You can find a video demonstration at the bottom of this article.

What is a Statrole?

Statroles assign and remove roles automatically based on minimum and optional maximum values of participation! A Statrole can be one of three Stat Types: Messages / Voice / Activity (games and applications). Voice has additional settings you can set for tracking different sub-types: AFK, muted, and deafened. Voice and Message both allow you to Whitelist or Blacklist channels. We’ll go in-depth on what this mean later. In addition to Stat Types are Limit Types which help you fine tune when people get roles. Statroles are checked and applied frequently, every 10 minutes. You can even set the same role for multiple Statroles!

What makes Statroles different than most other automatic role rewards/giving systems is that a newly configure Statrole will instantly have access to all the server’s history that has been tracked by Statbot. This means that you can now set up the role system at your leisure without worrying about having to commit to an inflexible system. Don’t like a Statrole? Edit its settings! Want to start fresh? Delete it, remove the role from the members, and pick up right where you left off whenever you choose with all the same stats but a different Statrole. No data lost. No time wasted.

Note: Statbot keeps track of who it adds and removes roles to/from. It uses this information to more efficiently assign roles. Manually adding or removing a role to/from a member is not supported. Adding the role to a member does not mean that it will be immediately removed by Statbot. In removing the role, the member would have to no longer meet the criteria of the Statrole, and then meet it again in order to be reassigned the role. This is also true for members that leave a server.

Limitations

Servers without the Statroles+ premium perk can create 2 Statroles of each Stat Type ( Message / Voice / Activity ) and are restricted to the Threshold Limit Type. Servers with the perk have no restrictions and are able to create as many Statroles as they want with any of the Limit Types.

Create a Statrole

Statroles are very easy to set up! Any server can create up to 2 Statroles of each type (Message / Voice / Activity) for a total of 6. Servers with the Statroles+ premium perk can create as many as they want!

You can get started right away by doing the following:

  • Navigate to the server Manage page. https://statbot.net/manage/<serverid>. Alternatively, navigate to your server’s dashboard (which you can find on your /me page) and click the “Manage” tab.
  • On the left side navigation under Configure, click on Statrole. On this screen you will see a list of the current Statroles if the server has any configured.
  • Click Add. You will be greeted by the window below:
Statrole Settings

Basic Settings (For All Statrole Types)

  • Name (Optional) – This only for you and will help you identify this Statrole in the list.
  • Role – The Discord role you want to assign to a member that meets the criteria of the Statrole.
  • Stat Type – Stats you would like the Statrole to apply to. ( Messages / Voice / Activity )
  • *Timerange [days] – The number of days back from each check you want the Statrole to be. Example: Setting this to 7 days will mean that only stats in the past 7 days will be looked when a check occurs. Members who meet the criteria will get the role. Members who no longer meet the criteria will be removed from it.

*Timerange is limited to 30 days for servers without the History premium perk. This setting is also the same for all Limit Types however carries a special meaning with the Day Range type which will be explained later.

There are additional settings that are specific to the different types of Statroles. Below are walk-throughs of those settings.

Different Statrole Limit Types

Threshold

Threshold is the default type of Statrole and is available to everyone. It’s defining settings are Minimum, Maximum, and Timerange as you can see above. Below are what each of these settings means for Threshold:

  • Minimum – Lowest amount of messages ( or minutes for Voice / Activity ) that a member must have in order to receive and keep the role.
  • Maximum (Optional) – Highest value for messages or minutes ( Voice / Activity ) that a member can have before they are no longer eligible for the role.

Assuming the stats are in the Timerange, if a member is above the Minimum and below the Maximum, they will receive and keep the role. If Maximum is not set, the member will keep the role so long as they are above the Minimum.

Average

For servers with the Statroles+ perk, Average acts much like the Threshold except that it average’s a member’s stats over the Timerange. It then uses this average and the Minimum and Maximum to determine if the member should have the role or not. Below are what each of these settings means for Average:

  • Minimum – Lowest amount of messages ( or minutes for Voice / Activity ) that a member’s average in the Timerange must be in order to receive and keep the role.
  • Maximum (Optional) – Highest value for messages or minutes ( Voice / Activity ) that a member’s average in the Timerange can be before they are no longer eligible for the role.

Top

For servers with the Statroles+ perk, Top applies the role to the members within a range sorted by the sum of their stats in the Timerange. Below are what each of the settings means for Top:

  • Lowest Rank – The bottom rank of the member who will get the role. (e.g. In “Top 10” this would be rank 10.)
  • Highest Rank (Optional) – The top rank of member who will get the role. (e.g. In “Top 11 through 20”, this would be rank 11.)

This is the perfect type for applying roles in a “leaderboard” fashion and offers all the same customization as any other Statrole. Not including the Highest Rank setting will have the Statrole act like any leaderboard. Including Highest Rank allows for setting tiers within the top list (much like you can do for Minimum and Maximum for the Threshold and Average types). Members at the bottom of the list who have the same count will both get the role (e.g. If two people are in “10th” place for Top 10, both will get the role).

Day Range

For servers with the Statroles+ perk, Day Range is perhaps the most powerful of all the Limit Types when understood and used effectively. Below are what each of these settings means for Day Range:

  • Minimum – The required amount of messages ( or minutes for Voice / Activity ) for a member’s activity to count in a day.
  • Required Days – The number of days that a member must reach the Minimum within the Timerange.
  • Timerange – The length of time a member has to meet the Minimum for the Required Days.

What this allows you to do is set a minimum level of activity that a member must meet each day but also allows them to miss a few here and there. If Timerange is set to “7” and Required Days is set to “5”, the member must meet the Minimum for 5 out of every 7 days. So even if the member has a huge spike in stats for one of those days, it won’t make them any more eligible for the role if they aren’t active on other days as well. Keep in mind the the Timerange slides just like with the other Limit Types.

Additional Settings

Channel Filtering (Message / Voice)

  • *Filter Channels?
    • You can whitelist or blacklist channels. When YES, you will see the below options. Select NO if you wish to include all the server’s channels that Statbot has access to in the check.
  • Filter Type
    • Whitelist
      • Channels in this list will be the only channels that are checked for this Statrole.
    • Blacklist
      • Channels in this list will not be included in the check for this Statrole.
  • Available
    • The list of all the channels in your server that Statbot has collected data from. Clicking one will move it over to the Selected section. When Type is Message, this list will only be text channels. When Type is Voice, this list will only be voice channels.
  • Include Deleted – Will show/hide deleted channels for the Available list (but not from the Selected list). Useful for when you want to whitelist/blacklist channels that you have already deleted from Discord.
  • Selected
    • A list of all currently selected channels that will be either Whitelisted or Blacklisted depending on the Filter Type described above.

*When Filter Channels? is YES, a channel must be added to the Selected list or it will be automatically changed to NO when the Statrole is saved.

Voice Types – (Voice)

  • Include Voice Types
    • Select the type of voice activity to include when checking the Statrole. Regular is checked by default.
      • Regular
        • Any time that is not any of the below types. (AFK, Self-Mute, Self-Deaf, Server-Mute, and Server-Deaf)
      • AFK
        • Time spent in the AFK channel. The AFK channel is a Discord setting and it found under “Server Settings”.
      • Self-Mute*
        • The time a member has themselves muted through Discord.
      • Self-Deaf
        • The time a member mutes their speakers through Discord.
      • Server-Mute
        • The time a member is muted by someone else with the permissions to do so in that server.
      • Server-Deaf
        • The time a member speakers are muted by someone else with the permissions to do so in that server.

*Note: A member without a functioning mic will have the same symbol as someone who is muted (crossed-off microphone). This does NOT count as being muted. Muted only occurs when the actual setting in Discord is used.

Activity

  • Activity
    • Select the Activity that you want the Statrole to be based on.
      IMPORTANT: You must setup Activity Tracking for this Activity as it is not on by default. You can CLICK HERE to learn more.

Usage Examples

Finding Inactive Members

While Statbot does not track members with no stats, there are some workarounds that you can use Statroles for to find members with no Message, Voice, or Activity stats in your server. Below are some of the ways other communities are using Statroles to find inactive members!

“Member” Role

If you want to mark members with any stats in your server as “safe”, a common method is to use a generic “Member” role and the Threshold Limit Type. (You can, of course, call the role whatever you want.) By setting the Minimum to 1 or another minimum standard of activity you have, you can mark members as “safe” for the duration of your Timerange. If you then hoist the Member role*, you can use the sidebar to see who has the Statrole and who doesn’t have any other hoisted roles** (example below).

You can even set a minimum amount of stats for different Stat Types with the same role! You can refer to Example One – Two Statroles; One Role below for a deep dive on how this behaves but the gist is that if the user falls into either Statrole, they will get the role!

* Note: In large servers, “Invisible” and “Offline” members will not show up under “Online” on the sidebar. We will have solutions for this in the future and you can keep up with our development by checking out our Trello Board!
** Note: This only works if the member does not have another hoisted role.

Advanced Usage Examples

Example One – Two Statroles; One Role

This example will go over how Statroles behave when you have more than one Statrole set with the same role. We will set up two Statroles, one Message and one Voice. Each will have a single role called Role A and a 7-day Timerange.

Settings
Statrole 1
*RoleRole A
*TypeMessage
*Minimum100 (messages)
*Timerange7

Statrole 2
*RoleRole A
*TypeVoice
*Minimum100 (minutes)
*Timerange7

What does this do?
Both of these Statroles will assign Role A to a member if they meet the requirements. This means that that member will receive the role if they match either Statrole 1 or Statrole 2. Meeting the requirements of both is the same as meeting the requirements for only one.
If the member no longer meets Statrole 1‘s requirements but still meets Statrole 2‘s, they will keep Role A. This remains true no matter what the Types of Statroles we are using.

Scenarios
The following scenarios demonstrate how the above Statroles will behave. The stats here fall within the Timerange of 7 days. For simplicity, “voice minutes” will be “minutes”.
1) 0 messages, 0 minutes – No roles.
2) 0 messages, 100 minutes – Give Role A.
3) 101 messages, 101 minutes – Keep Role A.
Time passes…
4) 90 messages, 101 minutes – Keep Role A.
Time passes…
5) 90 messages, 90 minutes – Remove Role A. No roles.

Takeaways
What this teaches us is that so long as one Statrole matches at the time of a check, the member will get/keep the role even if that role is used by another Statrole.

Example Two – Two Statroles; Same Stat Type

This example will go over how Statroles behave when we have Statroles with of the same Type with different Minimum and Maximum values. We will set up the two Message Statroles and have two roles, Role A and Role B.

Settings
Statrole 1
*RoleRole A
*TypeMessage
*Minimum100 (messages)
*Maximum199 (messages)
*Timerange7

Statrole 2
*RoleRole B
*TypeMessage
*Minimum200 (messages)
*Timerange7

What does this do?
Since these Statroles are the same Type and have Minimum and Maximum values that do not overlap, a member will only be able to meet the criteria of one at a time (or neither). When at or above 100 messages and at or below 199 messages, the member will get Role A from Statrole 1. When at or above 200 messages, the member will get Role B from Statrole 2. Role A at the point will be removed if they were given it by Statbot because the member no longer matches the criteria of Statrole 1.

Scenarios
The following scenarios demonstrate how the above Statroles will behave. The stats here fall within the Timerange of 7 days.
1) 0 messages – No roles.
2) 100 messages – Give Role A.
3) 200 messages – Remove Role A. Give Role B.
Time passes…
4) 150 messages – Remove Role B. Give Role A.
Time passes…
5) 50 messages – Remove Role A. No roles.
6) 250 messages – Give Role B.
Time passes…
7) 50 messages – Remove Role B.

Takeaways
What this teaches us is that we can chain Statroles of the same type together to create tiers that Statbot will move members between based on their stats. Also, a member does not need to receive the role of one tier to go to the next. In the case of 6), the member went past Statrole 1‘s Maximum of 199 and qualified for Statrole 2 so they got Role B; then in 7), they fell below both Statrole 2‘s and Statrole 1‘s Minimums so the only thing that happened was Statbot removed Role B.

Note: If Statrole 1 didn’t have a Max, or it was above what the member had at the time of the check, that member would get both Role A and Role B because they would match the criteria of both Statroles.

Video Overview and Demo