Modbot Docs
Discord

Role and ban sync

Keep VRChat group roles and Discord roles in step, and copy bans between the two, with a look at what would change before anything does.

Role and ban sync keeps your VRChat group and your Discord server in step with each other:

  • a role pair says that one group role goes with one Discord role, and which side decides;
  • ban sync copies a ban in one place into the other.

Everything here is off until you switch it on, and each direction is its own switch. A ban made directly in VRChat and a ban made directly in Discord stay separate until you switch copying on. The one exception is a ban made in Modbot, which reaches both places without any switch: see Bans made in Modbot.

This only ever touches people who have linked their accounts. Somebody in your Discord server with no VRChat account tied to them is never given a role, never has one taken away, and is never banned by this. That is most of a Discord server, and it stays that way.

Before you start

You need the Manage role and ban sync permission to set any of this up, and Run role and ban sync to copy what is already different.

The bot needs permissions in your Discord server, and only the ones you actually use:

What you switch onWhat the bot needs
Keep paired roles in stepManage Roles, and its own role above every role you pair
Copy group bans into Discord, as a banBan Members
Copy group bans into Discord, as a removalKick Members
A ban or unban made in Modbot reaching Discord (no switch)Ban Members, which the invite link does not ask for: give it to the bot in Discord yourself

Re-invite the bot with the link on Settings → Discord → Account linking after switching one on: the link asks for exactly what your settings need.

A ban made in Modbot also needs Ban Members to reach Discord, and no switch here asks the link for it. If you want those bans to reach Discord, give the bot Ban Members yourself; until you do, the ban still stands in the group and Modbot tells you Discord refused.

Pair a role

Settings → Discord → Role and ban sync.

Pick the two roles

Pick a group role and a Discord role. A role can be in one pair only, and a Discord role a list gives cannot be paired.

Choose who decides

Who decidesWhat happens
VRChatThe group role is the answer. The Discord role is given and taken away to match.
DiscordThe Discord role is the answer. The group role is given and taken away to match.
NobodyNothing is changed. A difference is written to the audit log and nothing else.

Start on Nobody if you are not sure. You can see the differences it finds in the audit log and change your mind later.

Name the rank

Optional. Type what your group calls this level, such as Owner, Moderator or Member, in the Rank box. It is your own word and Modbot never reads it: it only groups the out of step list. Several pairs can share a rank.

Switch role sync on

Keep paired roles in step, then Save sync. Modbot checks once a minute from then on.

Who is out of step

Show who is out of step lists every linked person who holds a paired role on one side and not the other, grouped by rank, with the role and the side they hold it on. Pairs with no rank come last, under No rank. It lists people on pairs that are switched on, whoever decides them, and changes nothing.

It reads what Modbot has already stored. Only people who have linked their accounts can be compared, so with nobody linked it says Nobody.

Unlinking takes back the Discord roles this sync gave them, within a minute. It only takes a role Modbot's own records show it gave to that Discord account, and only while nothing has taken it back since. A role somebody gave them by hand, or one they held before the sync ever ran, stays, and so does a role on a pair you have switched off or removed.

The group role stays too: the person is still in your group. Show what would change lists the roles it would take back, like any other change.

Copy bans

Two switches, one for each direction, and a third that only appears while the second is on.

  • Copy group bans into Discord — somebody banned from your VRChat group is banned in Discord, or removed from the server, whichever you pick.
  • Copy Discord bans into the group — somebody banned in Discord is banned from your VRChat group.
  • Copy bans made by other bots — shown while the switch above is on, and off by default. Bans made by another bot in your server (a moderation bot with rules of its own) are skipped, and so are the unbans it makes. Switch it on if you want those copied as well. Modbot's own bot is never copied, whatever this says.

A ban made by a person is copied whichever way that switch is set. When Modbot cannot tell who made a ban, it treats it as a person's.

Each copied ban records the reason the moderator typed in Discord, when there was one, in the Ban copied from the other platform entry of the audit log. VRChat's ban has nowhere to put a reason, so that entry is the only place it is kept.

Unbans follow the same switches. If group bans are copied into Discord, lifting a group ban lifts the Discord one too.

A Discord ban is often for something said in chat, by a moderator with no say over your VRChat group. Copying it into the group widens the punishment. Some communities want exactly that; decide on purpose.

Ban, or remove

A group ban can either ban the person in Discord or remove them from the server. A removal can be rejoined, so a later group unban does nothing in Discord — the person simply comes back.

What crosses over, and from when

Switching a direction on starts from that moment. Bans from before are not copied, so turning a switch on cannot ban a hundred people at once. Use Copy what is different when you want the older ones as well.

Modbot never copies a ban it made itself, in either direction.

Bans made in Modbot

A ban or unban made in Modbot, by a moderator or by an AutoMod rule, is made on both platforms: in your VRChat group, and on the person's linked Discord account, when Discord is set up and they have linked their accounts. No switch on this page is involved.

Somebody with no linked Discord account is banned in the group and nothing else happens. If Discord refuses, for instance because the bot has no Ban Members, the group ban still stands: the confirmation says what Discord answered, and the audit log has a A copy between platforms failed entry.

Modbot does not copy that Discord ban back into the group, or the group ban into Discord a second time.

See what would change first

Show what would change lists every difference and does nothing at all — no bans, no role changes, nothing written down. Read it before you press anything else.

Copy what is different also lists every difference first, without changing anything, then turns into a red Copy it and a Cancel. Press Copy it to make the changes, or Cancel to back out. On a server that has been running for a while this is the press that moves the most people, so look at the list first.

The first run only ever bans. It never lifts a ban, because "there is no ban here" and "the ban here was lifted" look the same before Modbot has any history of its own.

When something is wrong

The card shows when each half last ran and what went wrong.

What it saysWhat to do
The bot cannot assign a roleGive the bot Manage Roles, and move its own role above that one in Discord
The bot may not ban in this serverGive the bot Ban Members, and keep its role above the people it bans
The bot may not remove people from this serverGive the bot Kick Members

A ban that could not be copied because of a missing permission is copied on the next check once you fix it.

What goes in the audit log

Every copy is recorded against the person it happened to:

  • Ban copied from the other platform, Unban copied from the other platform. A ban or unban made in Modbot and made in Discord as well is recorded the same way, and says who made it.
  • Removed from Discord for a VRChat ban
  • Role given to match the other platform, Role taken away to match the other platform

A copy that failed, and a difference found on a pair nobody decides, go in the operational log instead.

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