Modbot Docs
Discord

Event channels and filters

Send bans, kicks, joins, role changes and other events to the Discord channels you choose, narrowed to the people and roles you care about.

The bot can post events to your Discord server as they happen: bans, kicks, warnings, people joining and leaving, role changes, case files and much more. You decide which events go to which channel, and you can narrow a channel to certain people or roles, for example "bans done by Moderators" or "anything that happens to these three people".

Each rule for a channel is set up on the Channels card under Settings → Discord. You need the Change settings permission. The bot has to be connected first; see Setting up the bot.

Add a channel

On the Channels card, press Add channel. The Add channel window has:

  1. Channel — pick the channel by name. A channel where the bot is missing a permission is marked with what is missing (see What the bot needs in the channel).
  2. Name — optional. It is shown next to the channel in the list, which helps when one channel has more than one rule.
  3. Events — tick the events to send. Events are grouped under headings; the box beside a heading ticks or clears the whole group, and the count beside it shows how many are ticked.
  4. Filters — all optional (see below).

Press Save. You must pick a channel and at least one event.

Which events can be chosen

Almost every kind of event Modbot records can be sent. They are grouped like this:

GroupExamples
ModerationBanned, Unbanned, Kicked, Kicked from an instance, Warned in an instance, Join request rejected, Case file written, Evidence attached, Review opened, Flagged by a moderation rule
MembersJoined the group, Left the group, Role granted, Role revoked, Asked to join the group, Profile changed, Seen as 18+ verified
InstancesGroup instance created, Group instance closed, Joined an instance, Left an instance, Changed avatar
GroupGroup details changed, Group post created, Calendar entry created
DiscordJoined Discord, Left Discord, Banned from Discord, Timed out on Discord, Discord role granted, Joined a voice channel, Discord messages removed by a moderator, Discord account linked
Access and settingsAccount created, Roles changed, Role created, API key created, Settings changed
OtherSync failed, AI spend limit reached, and anything that fits no other group

The window always lists the full set. When Modbot learns to record a new kind of event, it appears in the list without anyone having to add it.

Group instance closed also covers an instance that ended on its own. VRChat records a close only when a moderator closes an instance by hand; when one empties out instead, Modbot writes its own "Instance ended on its own" entry, and a channel that takes Group instance closed gets it too, so there is no second box to tick. Entries Modbot adds afterwards for instances that ended before it wrote them are history, and are never posted.

Events that are never sent

Some events are never posted to Discord, whatever a rule says, and are not offered in the list. A Discord channel is usually readable by many people, so these stay inside Modbot:

  • sign-ins and failed sign-ins;
  • password changes and password reset links;
  • Signed out everywhere;
  • contact detail changes;
  • Modbot's own housekeeping, such as Posted to the Discord log channel.

Filters

Leave every filter empty to send all events of the ticked kinds.

FilterAn event is sent only when
Happened toit happened to one of these people.
Happened to someone with these VRChat rolesthe person it happened to held one of these VRChat group roles at the time.
Done byone of these people did it. Tick Modbot (automatic) to also include events nobody did, such as changes Modbot noticed on its own.
Done by someone with these VRChat rolesthe person who did it held one of these VRChat group roles at the time.
Done by someone with these Modbot rolesthe Modbot account of the person who did it held one of these Modbot roles at the time.

How filters combine. When you set more than one filter, an event has to pass all of them. Inside one filter, matching any of the listed people or roles is enough.

Events nobody did. An event with no one who did it never passes Done by someone with these VRChat roles or Done by someone with these Modbot roles. It only passes Done by when Modbot (automatic) is ticked.

Picking people

Type a name or id in the search box under Happened to or Done by. The results come from the VRChat profiles Modbot has stored, the Discord server's member list, and the Discord accounts members have linked. Each result is marked VRChat or Discord. If the person is not found, you can pick Use … as a VRChat id or Use … as a Discord id to use what you typed as it is.

  • A VRChat account matches events about that VRChat account.
  • A Discord account matches events about that Discord account, whether or not the person has ever linked a VRChat account.
  • When a member has linked their accounts (see Account linking), picking either account also matches events on the other one.
  • A moderator's actions in Modbot count as done by the VRChat account linked to their Modbot account, and by the Discord account on it.

Roles are the roles at the time

Roles are checked as they were when the event happened, not when the post goes out. If a Moderator bans someone while the bot is offline and then loses the Moderator role, a "bans by Moderators" channel still gets that ban.

VRChat roles are the group roles Modbot last read from VRChat. Modbot roles are the roles on the Roles page.

More than one rule for a channel

You can add as many channels as you like, and more than one rule for the same channel. If two rules for one channel both match an event, the channel still gets it only once.

The channel list

Each row on the Channels card shows:

  • the channel name, and the rule's Name if it has one;
  • a warning such as Missing Send Messages or Removed if the bot cannot post there;
  • how many events it sends, and Filtered when any filter is set;
  • an on/off switch, Edit and Delete. Delete asks you to press Delete again to confirm.

Every change is saved as soon as you make it, and recorded in the audit log as Settings changed with who made it.

Turning a channel on and off

The switch on each row turns a rule on (On) or off (Off). A rule that is off is kept but sends nothing.

Posting starts from the moment a channel is turned on. Nothing that happened before is posted. Adding a channel, or turning a channel back on after every rule for it was off, never replays your group's history into Discord.

What a post looks like

Each event is a card headed by the person it happened to: their display name, with their VRChat picture beside it. Under that:

  • the event's name as the title, for example Banned;
  • By whom, when somebody did it;
  • When, shown in each reader's own time zone;
  • VRChat's own sentence about the event, quoted, when VRChat gave one;
  • the group's name at the bottom.

A card about something on Discord is headed by the member's name as your server shows it, with their Discord picture beside it, and opens their Discord profile in Modbot. When Modbot does not know their name, the card shows them under Who with Discord's own mention, which Discord draws as their name and which pings nobody. A Discord moderator in By opens their profile too. A card about one of the server's channels or roles is titled by the channel or role, with what happened above it.

Some cards carry more:

  • a Discord ban, unban, kick or timeout: the Reason the Discord moderator typed, when they typed one;
  • a Discord timeout: Until when it ends;
  • a ban, kick or unban made from Modbot: the Reason the moderator picked. VRChat's own record of the same ban only says Modbot did it, so its card adds Decided by, the moderator who pressed the button, with the same reason. The note a moderator writes beside the reasons is never on these cards. A note only reaches a channel if a rule for it sends Note added;
  • messages removed: how many, under Messages.

When a public address is set, the title and every name on the card open that person in Modbot. Without one, the names are still there; they just are not links.

Cards do not print VRChat or Discord ids. The link carries the id, and the person's profile in Modbot shows it with a button that copies it. The one card that still shows an id is a card for somebody Modbot has no name for, where the id is all there is to show.

VRChat pictures are sent to Discord with the message, because VRChat does not let anyone else's server load its pictures. Discord pictures are Discord's own, so they are not sent. A picture Modbot cannot fetch just is not there, and the card is posted without it.

Modbot looks for new events every few seconds. When many events arrive at once, it groups up to ten cards in one message and spaces messages out, so it stays within Discord's limits. Events go out in the order they happened, and none are skipped.

A message with one card in it gets buttons for the person it is about: Add note, Kick and Ban, Approve and Reject on a join request, and Open case on a ban with a case file. See Acting from Discord.

Repeats are folded into one post

When the same thing changes again, the bot edits its last post instead of posting a new one. The title then says how many times and over how long, for example Group details changed · 12 times in 55m, and the card shows the latest change and when it happened. This happens only when:

  • it is the same kind of change, to the same thing, by the same person (or by nobody, for changes Modbot noticed on its own), and it touches the same fields. A change to the group's rules among readings of how many members are online gets a post of its own, so it is never hidden in the count;
  • the post would cover no more than an hour, from the first change to the latest;
  • the bot's post is still the last message in the channel. If anyone posted after it, the change gets a post of its own, so the channel still reads in order.

The changes that fold this way are Group details changed, Group profile changed, Role changed, Group instance changed, Recurring calendar entry changed, Profile changed, Changed avatar, Discord nickname changed, Discord channel changed and Discord role changed. Bans, kicks, joins, leaves, notes and every other action always get a post each. If you delete a folded post, the next change starts a new one.

What the bot needs in the channel

The bot needs View Channels, Send Messages and Embed Links in each channel it posts to. These can be taken away by a channel's or category's own permission settings, even when the bot's role has them. To fold repeats into one post it also needs Read Message History; without it, every repeat is posted on its own.

If Discord refuses a post, that channel waits 30 seconds and tries again from the same event, so nothing is lost. Other channels keep posting in the meantime. The Discord bot card on the Health page lists each channel with a problem: missing permissions, a deleted channel, or the reason Discord gave for refusing the last post.

Insights

AI insights can also be posted to a Discord channel. That is set up with the insights themselves; see Insights.

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