Modbot Docs
Discord

Modbot roles from Discord

Link a Discord role to a Modbot role, so staff get and lose their Modbot permissions when they get and lose their Discord staff roles.

If your team already decides who is staff with Discord roles, Modbot can follow them. You link a Discord role to a Modbot role, and from then on somebody given that Discord role gets the Modbot role within about a minute, and loses it within about a minute of losing the Discord role.

Nothing happens until you set it up. There are no linked roles until you make one, and every linked role names one Discord role, one Modbot role and which way it works. A role you have not linked is never looked at.

Before you start

You need both Manage roles and Manage users. A linked role changes who holds a role, so it asks for what changing somebody's roles by hand asks for.

The Discord bot must be in your server. It only needs to read the member list, which it already does, unless you use Both ways (below).

Who it reaches

Only staff accounts that already exist and have proven their Discord account from their account page (Connect with a code or Connect Discord, see Staff accounts). Everybody else is left alone:

  • A Discord account that was only typed in, not proven, never counts here, not even before 1 November 2026.
  • Administrators are never touched, and nor is the owner. A Discord role can't give Administrator, or any role that includes it.
  • Disabled accounts are left as they are.
  • Modbot never makes accounts. Somebody who holds a linked Discord role and has no Modbot account shows up in the preview under Left alone, so you know whom to invite.

Where to set it up

The same list, in two places. A linked role made in one shows in the other.

  • Settings → Discord → Modbot roles from Discord: every linked role, the switch, and Apply.
  • Settings → People and roles → Roles: open a role, and its Discord roles are listed under its permissions.

Pick the roles

Pick a Discord role and, on the Settings card, a Modbot role. @everyone and roles that belong to bots can't be used. One Discord role gives one Modbot role, but several Discord roles can give the same Modbot role, and holding any of them is enough. Fourteen department roles can all give Moderator.

You can only link a Modbot role that is below your own highest role and allows nothing you can't do yourself: the same rule as giving somebody a role by hand.

Choose which way it works

Which wayWhat happens
Discord decidesThe Discord role is the answer. Modbot gives and takes the Modbot role to match, and never changes anything in Discord.
Both waysAs above, and giving or taking the Modbot role in Modbot gives or takes the Discord role too.

Look at who would change, then save

Add shows Who would change before anything is saved: who would get the role, who would lose it, and whether they had it from Discord or were given it by hand. Press Save, or Cancel to back out. Changing which way a linked role works shows the same list.

Switch it on

Give Modbot roles from Discord roles is off to begin with. Turning it on shows the list once more, for every linked role, then Turn on. While it is off nothing is given or taken, and on the Roles page the linked roles show Off.

What happens

They…Modbot…
get a linked Discord rolegives the Modbot role
lose it (and hold no other Discord role that gives the same Modbot role)takes the Modbot role away; the account stays, even with no role left
leave the Discord servertakes the Modbot role away
take their Discord account off their Modbot accounttakes away every role a linked role gave them
hold the Modbot role from before, given by hand, but not the Discord roletakes it away: Discord decides

On an account a linked role reaches, a role that follows Discord can't be given or taken by hand on the Users page: its box is greyed out. A Both ways role can, and the change goes to Discord.

Removing a linked role takes nothing away. The roles it gave stay as ordinary roles.

A change shows on the person's next click; they don't need to sign in again.

Both ways

The bot needs Manage Roles in your server, and its own role must be above the Discord role. A Both ways Discord role can't be one that can ban, kick, manage the server or manage roles, and can't also be in a role pair with a group role, or a role a list gives. If the Discord role gains one of those permissions later, the linked role becomes Not set up.

When the bot can't give the role, or Discord refuses when it tries, the linked role says Not set up. Until you fix that it works as Discord decides: changes in Discord still reach Modbot, and the role can't be changed by hand in Modbot. After a refusal the bot asks Discord again once a day, or as soon as a role in your server changes, such as the bot's own role moving up.

A Both ways Modbot role can have only one Discord role, so Modbot knows which one to give.

Whichever side changed is copied to the other, and a change Modbot made itself never bounces back. The first time a linked role is checked, whichever side holds the role gives it to the other, except for somebody who connected a Discord account after the linked role was saved: for them Discord decides. Connecting a different Discord account never carries the role over to it. Somebody who isn't in the server always counts as not holding the Discord role, so they lose the Modbot role and Modbot never tries to give them the Discord role.

Stopped: too many at once

If one check would take roles away from more than five accounts at once, or from more than half of the accounts it reaches (and at least three), Modbot takes nothing away, the card says Stopped, and Apply appears. This catches a Discord role deleted by mistake, or the bot losing sight of the member list. Press Apply to see the list, then Apply again to carry it out. You can only apply it if you could make each of those changes by hand: every role and every account in the list must be below your own highest role.

Giving roles goes on while it is stopped.

Modbot also waits after the bot reconnects until it has read the member list again, so it never acts on roles from before the bot went away.

When Modbot isn't receiving member updates

Linked roles follow the member roles Modbot keeps, and those only stay current while Discord sends the bot member updates: the bot must be online and have the Server Members Intent (see bot setup). Without them, somebody taken off staff in Discord would keep their Modbot role. So while they are missing Modbot gives and takes nothing. After ten minutes, counted from the last update or from when Modbot started, every linked role says Not set up, the card and Health say "Modbot isn't receiving member updates from Discord.", the audit log records it once, and linked roles can't be changed by hand. Once updates arrive again, it carries on. The card shows this before you add any link too.

What goes in the audit log

In the operational log:

  • Roles changed, with no person as the one who did it, saying Modbot changed the roles to match Discord.
  • Discord role given a Modbot role and Discord role no longer gives a Modbot role, saying who linked or unlinked the roles.
  • Roles from Discord stopped, once, when too many would have lost a role at once, and Roles from Discord applied, saying who pressed Apply.
  • Turning the switch on or off, like any other setting.

For Both ways, a Discord role Modbot gives or takes is recorded against the person like a role sync copy, and a refusal from Discord as one failed copy.

Modbot is not endorsed by or affiliated with VRChat Inc. or Discord Inc. VRChat is a trademark of VRChat Inc. Discord is a trademark of Discord Inc. SteamVR is a trademark of Valve Corporation. Windows is a trademark of Microsoft Corporation. Docker is a trademark of Docker, Inc. PostgreSQL is a trademark of the PostgreSQL Community Association of Canada. Railway is a trademark of Railway Corp. Other names are trademarks of their respective owners; see Legal. Modbot and its logo are trademarks of the Modbot project. Open source under AGPL-3.0.

On this page