How to set up Discord auto roles and self roles

Before you start

• Have a running bot in your own test server and Pro. The ongoing Free module set does not include Role Management.
• Create two ordinary Discord roles named Newcomer and Events. Keep their permissions limited, place them below the bot’s highest role, and give the bot Manage Roles. Staff configuring these lists through Discord need Manage Roles too.

1. Enable Role Management and check the hierarchy

   From your bot’s Modules tab, enable Role Management and open its Settings. Select the server that contains your test roles, then check Enable Role Management Commands. Keep Enable Role Persistence off for now so the first join test has only one source of role assignments. Leave Allow Self Assign and Allow Self Remove enabled. Save the configuration before moving to Discord. The examples below assume the default ! prefix; if your bot uses another prefix, replace that leading character while keeping the command name and arguments the same.

   Check the actual role order in Discord before troubleshooting the module. The bot must be able to manage each target role; a role above the bot cannot be assigned just because it appears in a saved list. Use ordinary roles created for this exercise, rather than an integration-managed role or the server’s everyone role. Confirm that Newcomer does not open a staff category and Events does not grant moderation powers. Automatic assignment is convenient precisely because it bypasses a manual approval step, so its permissions should suit every person who can receive it.

2. Add a join role and verify a fresh arrival

   Add Newcomer to Auto Roles in the dashboard, or enter !autorole add Newcomer from a staff account in Discord. Inspect the saved selection with !autorole list. The command accepts a role mention, ID, or name; a unique name is convenient for this small example, while an ID avoids ambiguity when several roles have similar names. Auto Roles is a list of roles for future join events. Adding a role here does not sweep through all existing members and assign it retroactively, so test with a fresh arrival.

   Ask a consenting test member to join the disposable server while the bot is online. Inspect their Discord profile and confirm that Newcomer appears. Bot accounts are ignored by this join handler, so inviting another bot is not a substitute for this check. If the role is absent, review the selected server, module switch, saved list, and role hierarchy. For an optional audit trail, set Role Log Channel to a text channel the bot can write to. Verify the member’s actual roles even when a log is present; the profile is the practical result your members experience.

3. Offer a role members can choose themselves

   Place Events in Self-Assignable Roles, or configure it with !selfrole add Events. A member can inspect the available choices with !selfroles and request the role with !iam Events. Check their profile again to confirm the assignment, then ask them to enter !iamnot Events and confirm removal. These member commands operate on the approved list. Staff configure that list separately, so members do not need Manage Roles simply to choose an approved interest. Keep both Allow Self Assign and Allow Self Remove on during this test.

   Max Self Roles Per Member defaults to 5 and accepts settings from 1 through 25. The check counts roles the member already holds that are in the configured self-role list, even if another workflow originally assigned them. Avoid putting Newcomer in that list unless it really should count as a member choice. This is a module setting rather than a subscription allowance. If someone reaches the chosen maximum, they can remove an approved role before selecting another. Explain that behavior where you publish the choices so a refusal is not mistaken for a broken bot.

4. Check exclusions and remove choices carefully

   Excluded Roles prevents a role from remaining in the self-assignable list and excludes it when new persistence snapshots are collected. It is not a universal denylist for every assignment path. In particular, an excluded role can still be in Auto Roles, and the join handler does not recheck exclusions against an older saved persistence entry. Before changing policy on a sensitive role, remove it from Auto Roles and review or clear the persisted cache as appropriate. Do not assume that selecting an exclusion revokes roles already held by members.

   Removing Events with !selfrole remove Events stops it being an approved choice, but leaves current holders untouched. It also means those holders can no longer remove that role through !iamnot Events, because removal checks the same approved list. Arrange staff cleanup before retiring a widely used self role. For a particular member, staff can use !removerole followed by a member mention and the role name; !giverole with the same arguments assigns one manually. These manual actions check the bot’s ability to edit the role and the invoking staff member’s role hierarchy.

5. Try sticky roles only after reviewing saved access

   Enable Role Persistence if returning members should recover eligible roles from their previous membership. The equivalent Discord command is !rolepersist on. With the feature enabled, the leave handler saves eligible roles, and a later join combines saved roles with Auto Roles. Persistence excludes the everyone role, managed roles, roles the bot cannot edit, and configured exclusions when collecting a snapshot. Test this with the harmless Events role: assign it to your volunteer, have them leave, and then invite them back. Confirm that the expected roles return without adding an unrelated staff role.

   The snapshot cache is bounded. Max Persisted Members defaults to 500 and supports 10 through 5000 entries; each member’s saved role list is capped at 50. Auto Roles and persisted roles are combined into a list capped at 50 on join, so restoration is not an unlimited backup of all server roles. Staff can inspect the cache status with !rolepersist status and refresh one member’s snapshot with !rolepersist sync followed by their mention. That sync targets a member, not the entire server. Treat persistence as a convenience for the roles you have deliberately reviewed.

6. Publish instructions and keep the lists current

   Tell members which roles arrive automatically and which they can choose. Include the self-role list and both assignment and removal examples in your onboarding explanation. If you prefer a clickable reaction panel instead, follow the related Reaction Roles guide; this walkthrough uses the Role Management commands. Recheck your setup after renaming roles, moving the bot in the hierarchy, or changing channel permissions. A role can keep the same name while its access changes, so periodic review should consider what the role permits as well as whether the bot can still assign it.

   To stop future Newcomer assignments, enter !autorole remove Newcomer; existing holders retain it. To pause sticky-role restoration, enter !rolepersist off. That switch retains saved snapshots, while !rolepersist clear removes the entire stored cache, so choose deliberately. Turning off Enable Role Management Commands also stops this module’s join and leave processing, not just its text commands. Review the current switches with !rolesettings show before diagnosing a later failure. Once the test behaves as intended, use the signup button below to configure your own hosted role workflow on Pro.

   Need an event role that expires after two hours? Open Temporary Roles in Related modules below for the timed-access example. An authorised organiser grants that role manually through the separate Pro module. It refuses a role the member already holds, so use a dedicated event role outside your auto-role, self-role and sticky-role workflow.