¶ Welcome to CSV,Roles Docs!
¶ Current version: 3.10.0
CSV,Roles is a simple bot that aims to solve one problem. Mass assigning roles to or removing roles from your list of members via an uploaded CSV file.
Enjoying the bot? Buy me a coffee
¶ How does it work?
It's quite simple.
- Create a new .csv file and add a row of data to represent the header, then paste in the entire row of member names or IDs from your online form data and save it. (Make sure it is 'UTF-8' encoded)
- Head into Discord and use the
/assign-roleor/remove-rolecommand where you select a role and drop in your newly created csv file. - Wait a few minutes for the bot to process your list of members.
- Once complete, you will see a "Process complete" message and an attached log file to show you any errors that may have come up.
Discord has rate limits on role assignment. This is mostly handled automatically,
but would limit the bot to how quickly it can process larger lists. You can estimate
that it will take up to 75 (down from 90) seconds per 60 members.
¶ Action Outcomes:
- Success: Role assigned to (or removed from) the member.
- Failed: Member not found (likely left the server).
- Skipped: Member already has (doesn't have) the role.
¶ Prerequisites
The requirements for this bot to work are very simple.
- The CSV file must contain member username, server nickname, or ID in the first column of data (IDs are best)
- The file must not contain more than 1000 rows of data (not including the header)
- The file must also contain a header. The name of the header doesn't matter, but the first row will ALWAYS be expected and skipped. If you do not add a header, your first member will be skipped.
- The file MUST be encoded to utf-8.
CSV would look something like this (minus the row numbers):
discord usernames/ids,
nickname1,
member2#1234,
nickname2,
1234567890123,
3213549876543,
¶ Command Overview
Here is a quick rundown of all the bot's commands, their required permissions, parameters, and a short description of the command.
Notice: Parameters inside
[]are to be considered required, while()are optional parameters.
| Command | Req. Permissions | Parameters | Description |
|---|---|---|---|
/assign-role |
Manage Roles | [role]: Role to be assigned.[file]: Upload your CSV file.(header): Enter user identifier header name (defaults to first column if not specified). |
Assign the selected role to members in bulk via CSV upload. |
/remove-role |
Manage Roles | [role]: Role to be removed.[file]: Upload your CSV File.(header): Enter user identifier header name (defaults to first column if not specified). |
Remove the selected role from members in bulk via CSV upload. |
/role permissions |
None | [role]: Select a role to view its permissions |
View a role's permissions. |
/role members |
None | [role]: Select a role to view its members. |
View a role's members. |
/export-users |
Manage Roles | (filter_role): Export only members with this role.(include_bots): Include or exclude bots from the export. |
Export server members to a csv file. |
/invite |
None | None | Display an invite link for the bot. |
/help |
None | (command): View specific help info about this command. |
View the bot's commands, their parameters, and descriptions. |
/links |
None | None | View links for support, documentation, and more. |
¶ Command Details
New in Version 3.9.0
A new optional parameter has been added to both /assign-role and /remove-role commands.
This optional paramater will allow you to specify the name of the header where your user identifiers are located.
Example File:
affiliate name, discord user
dlchamp, .dlchamp
Example command:
/assign-role role: @test, file: members.csv, header: discord user
¶ /assign-role
Assign a selected role to a bulk list of members via csv upload.
Identifiers:
- Unique ID (best)
- username (requires
#xxxxif using old username still) - global nickname
- server nickname
File Requirements:
- CSV file must be encoded in utf-8 and contain a header.
- Must contain no more than 1000 rows, not including the header.
- Identifier must be in first column. Any extra columns are ignored.
- You can mix and match your list of IDs and names.
Minimum example
user
173105961442082816
...
Username lookup priority:
- look for nickname
- look for global nickname
- look for username
- If none found, a FAILURE line is logged for that user.
Note: If multiple users share any of the above identifiers, only the first occurrence will be found.
¶ /remove-role
Remove a selected role from a bulk list of members via csv upload.
Identifiers:
- Unique ID (best)
- username (requires
#xxxxif using old username still) - global nickname
- server nickname
File Requirements:
- CSV file must be encoded in utf-8 and contain a header.
- Must contain no more than 1000 rows, not including the header.
- Identifier must be in first column. Any extra columns are ignored.
- You can mix and match your list of IDs and names.
Minimum example
user
173105961442082816
...
Username lookup priority:
- look for nickname
- look for global nickname
- look for username
- If none found, a FAILURE line is logged for that user.
Note: If multiple users share any of the above identifiers, only the first occurrence will be found.
¶ /export-users
Export server members as a CSV File.
Exported file includes ID, username, server nickname, roles, user type, and join date (utc).
ID,Username,Display Name,Roles,User Type, Join Date,
173105961442082816,dlchamp,DLCHAMP,"[Contributor,Support,Chat Mod,Developer,Moderator]",Human,2022-02-27 17:20:32.198000+00:00
...
¶ Export Configuration (New in v3.10!)
You now have more control over the export!
When you use the /export-users command you will be greeted with a new configuration screen.
Within this configuration screen you will be able to:
- Include up to 25 roles to be included in the export
- Include up to 25 roles to be excluded from the export.
- Include or exclude bot users with the click of a button.
- By default the export will include ALL members, humans and bots
- A role can only exist in one list or the other.
- If a member has any of the excluded roles, they will not be exported, even if they have one of the included roles.