SCHS Robotics Roles Bot

A Python-based Discord bot that backs up and restores the roles and nicknames of the server's users.

Development is hosted at GitHub.com/jabernat/SCHS-Robotics-Roles-Bot.

Setup

Profile Creation

A bot profile for the SCHS Robotics server named @SCHS-Robotics-Roles-Bot has already been created on the Discord Developers Portal, giving this script an identity for users to interact with. If you are modifying this script for your own server, follow the start of Discord's app creation guide to creating your own bot profile. This bot profile was configured with the following settings:

• Public Bot: false so that only the bot profile's creator can invite it to servers.

• Privileged Gateway Intents: GUILD_MEMBERS (AKA "server members")

  This is required for the bot to request a complete listing of the server's users when reading and writing roles and display names.

Invitation

With a bot profile created, it must be invited to your Discord server by following the URL generated by the Developer Portal's OAuth2 URL Generator. When generating @SCHS-Robotics-Roles-Bot's invitation link, the following settings were used:

• OAuth2 Scopes:

  • bot: Allows the bot to appear in the users list and interact with users.
  • applications.commands: Lets the bot respond to slash commands like /roles_backup.

• Permissions:

  • ATTACH_FILES: Required to attach backup files to command responses during /roles_backup and /roles_restore.
  • MANAGE_NICKNAMES: Required to modify the display names of users during /roles_restore.
  • MANAGE_ROLES (AKA "Manage Permissions"): Required to add and remove users' roles during /roles_restore.

The generated URL was further customized to only allow invitation to the SCHS Robotics server, resulting in this final invitation link:

https://discord.com/api/oauth2/authorize
?client_id=1158245940516364308
&scope=applications.commands%20bot
&permissions=402685952
&guild_id=177211185177821184
&disable_guild_select=true

Following that link and accepting its confirmations will allow the bot profile to join the server.

Server Configuration

After the bot profile has joined the server, its name appears as a new role in the server's settings page. The permissions for bot actions have complicated interplay with the ordering of roles in the server's settings page. In short, the bot's new role should be reordered to between roles that should and shouldn't be affected by the bot; Administrator and mentor roles should come before it, and team roles, @Active, and @Alumni should come after it.

To limit the bot's interaction to certain channels or to certain roles, use the server's "Integrations" settings page.

Startup

Only one instance of the bot script should connect to Discord's servers to appear online. To connect it, execute either roles_bot.bat (on Windows) or roles_bot.sh (on Linux/macOS) to install dependencies, lint roles_bot.py with Mypy, and then execute the bot.

Note: The script looks for a bot token generated by Discord's Developer Portal in the SCHS_ROBOTICS_ROLES_BOT_TOKEN environment variable, or prompts for it at startup without showing input.

Commands

Once the script logs in, the bot will appear online in the server and accept commands from users with role and nickname management permissions. The bot accepts the following slash commands.

Warning: Care must be taken not to manually update user roles during any of these commands.

Command /roles_help

Responds with information about this bot.

Command /roles_backup

Captures the role assignments of the server's users and responds with a UTF8-encoded gzipped CSV file attachment structured as follows:

"User ID","Username","Display Name","Role 1 Name","Role 2 Name"
"#12345","user_1","User One",1,0
"#67890","Usr2#9999","User Two",0,0

Command /roles_restore

Accepts a gzipped CSV file attachment in the same format as generated by /roles_backup and then attempts to revert user display names and roles to that state. Users and roles not present in the file are not affected.

Terms of Use

Backup CSV files generated by this bot must only be used for recovery purposes by this same bot. Server administrators should delete backup files after their useful lifetime as they contain Discord handles, first names, and last initials. Scraping this data from Discord servers for purposes other than interaction with this bot is against the Discord Terms of Service.

Privacy Policy

This bot does not persist any user data, and only uploads its backup files to the Discord channel where they were requested. No data is shared with third parties. Because this bot is not operated by a for-profit company, it is exempt from the California Consumer Privacy Act (CCPA).