Auto Roles - kabiiQ/FBK GitHub Wiki
Autoroles are rules which can be set up to automatically assign users certain roles in your server when they perform certain actions.
All autorole commands follow the basic command format of /autorole <trigger type> <create/remove/list> <parameters>.
🔐 Modifying a server's autorole rules requires you to have the
Manage Rolespermission in that server.
- Users selecting roles with Buttons
- Users joining your server
- Users joining/leaving a voice channel
- Users reacting to a specific message
Users can be allowed to select roles in a server using Buttons. Buttons are a relatively new Discord feature and are good to replace "reaction" role assignment entirely.
They can be used similarly to reaction roles, and there is a command to convert directly from exisitng FBK reaction roles.
With buttons, the bot must send the message that the buttons will be added to. However, you are still able to edit this message later using commands.
Command: /autorole button create <STYLE> (message)
Both style and message are optional when creating a new button role message. They can be set here, or edited later on after adding roles.
The message is the content sent within the bot embed. You can always edit this later.
The style can be set to either buttons or dropdown.
The buttons style will use a dedicated button for each role added to this message, while the dropdown style will use a drop-down list allowing users to select their roles. In general, dropdown makes more sense if you are adding more than one or two roles. The dropdown style allows users to see which roles from this message they currently have selected when they go to edit their roles.
Command: /autorole button addrole <ID> <ROLE> (info) (emoji) (name)
ID is the message ID of the button role message to add a role to. Clicking on this field provides autocomplete suggestions of all the active button role messages in this channel.
ROLE is the role that users can add/remove by interacting with the button role message. Clicking on this field allows you to select any role from your server, but please ensure FBK has permission to assign users to this role (Manage Role permissions and a role ABOVE the role being assigned).
info is an optional field for a description of the role. It is displayed in the dropdown style and next to the roles in the message (if listroles is enabled on the message).
emoji is an emoji representing this role. It is displayed similarly to the info field.
name is an alternative name to represent this role. It is displayed on both button and dropdown styles, if you would like users to see a different name than the actual role name when they select their roles.
Command: /autorole button removerole <ID> <ROLE>
Both the ID and ROLE fields will provide autocomplete suggestions to quickly provide valid IDs.
Command: /autorole button edit <ID> (style) (message) (maxroles) (listroles)
The edit command allows you to change an existing button role message, with some additional options.
style and message can be changed at any time and have the same role as described in creating a button role message.
maxroles can be set to the number of maximum roles a user can select from this message. This limitation only works with the dropdown style, as it provides an interactive way to represent the limit. The default value, 0, represents no limit on roles selected.
listroles can be disabled to remove the "listing" of roles in the button role message, which will otherwise be included underneath the message that is set.
Command: /autorole button delete <ID>
Command: /autorole button convert <MESSAGE ID> <STYLE>
The convert command allows you to create a button role message in the current channel, with information copied from an existing FBK reaction role setup.
END OF BUTTON ROLES INFO. It is highly recommended to use button roles over reaction roles.
A role can be automatically assigned to users joining your server. You can configure this to only give the role to users joining with a specific invite*, or to any user joining the server.
❓ For this type of rule, you will specify the role to be used, to integrate this feature into your existing permissions setup.
Command: /autorole join create <ROLE>
❗️ Discord does not provide exact data on the invite code a user used to join a server. If you are using the autorole feature for specific invite codes, FBK will assume which code was used by viewing the invite code "usage", but FBK and in fact no Discord bot can guarantee 100% which invite code was used.
I have not seen this feature return an incorrect invite code, but if users are rapidly joining the server, this information may be delayed by Discord. If FBK can not safely assume which code was used, the autorole rule will be ignored, and only autoroles configured for "all" users will be assigned.
Unfortunately then, you should not attempt to create an invite that assigns "moderator" perms with this or any Discord bot, however seperate roles for your "Twitch" and "YouTube" invites would be safe.
Command: /autorole join create <ROLE> <INVITE>
Example: /autorole join create [@Twitch Viewer] [ucVhtnh]
Role must already exist on server:
You can remove an existing autorole by using an identical command to creation, but with the remove target instead of create.
Command: /autorole join remove <ROLE> (INVITE)
Command: /autorole join list
A role can automatically be assigned to users who are in a voice channel, and removed when they leave the channel. This can be configured to only give the role to user's joining a specific voice channel, or to give a general role to users in any voice channel.
For a common use case, this can be combined with basic Discord permissions to create text channels only visible for people in voice chat.
❓ For type of autorole, the bot will create a role when an autorole rule is created. You can then rename or recolor this role as you wish.
Command usage: /autorole voice create
Command usage: /autorole voice delete
Command: /autorole voice create <channel=VOICE CHANNEL>
Example: /autorole voice delete [channel=#Voice]
Command: /autorole voice list
It is recommended to use Button Roles (at the top of this page) instead of reaction roles. Reactions were not originally intended for this use, and we finally have a proper alternative.
A role can automatically be assigned to users reacting to a specific pre-configured message.
❗️ This type of autorole will require you to find a message's ID. You can use Discord's Developer Mode to find the ID of any Discord object, including messages. See the Discord help article on retrieving Discord user IDs.
❓ For this type of autorole, you will specify both an existing message and an existing role to be used. This allows you to set up the message content and layout in the way that best fits your server.
This type of autorole allows you to set up a message that will allow users to add or remove a specific role from themselves using reactions.
When an autorole rule is created, the bot will add the reaction of your choice to the specified message. Users can add/remove a reaction at any time to toggle their assignment to this single role.
🙂 You can select the autorole's emoji from any basic emoji supported by Discord, or from custom server emotes. When using custom server emotes, the bot must be in the server the emote is from. As such, it is recommended to use only emotes from your own server.
Command: /autorole reaction add <MESSAGE ID> <EMOJI> <ROLE>
Command example: /autorole reaction add [message=680668971833491470] [emoji=❤️] [role=@Twitch Notifications]
Command: /autorole reaction remove <MESSAGE ID> (EMOJI)
If the emoji is specified, only that specific emoji's reaction-role will be removed.
Example: autorole reaction remove [message=680668971833491470] [emoji=❤️]
If the emoji is not specified, all reaction roles will be removed from this message.
Example: /autorole reaction remove [message=680668971833491470]
Command: /autorole reaction list
Manual emote count reset: /autorole reaction reset
If there are too many reactions on a single message (this is several thousand), Discord may stop consistently sending enough reactions to make the channel work for reaction-roles. /autorole reaction reset can be used to reset the reaction counts for this channel back to 0 to work around this.
Another option is to run /cleanreactionscfg clean Enabled to automatically remove user reactions after they use the channel. This is not the default behavior as it is less user-friendly. Users going to the channel will not be able to see which reaction-roles they previously selected.