moderation

Automod

A bot you run on your own computer that watches rooms and steps in when a message trips a filter. It uses a normal account, so it only has the moderator powers you give that account. Built on bot accounts.

What it does

Automod signs in, joins the room(s) you decide, and reads new messages. A hit is deleted. Repeat hits from the same person within an hour fire automated moderation: warnings for the first two hits, a 5 minute mute for the 3rd hit, a kick for the 4th hit, then a permanent ban for the 5th hit. File attachments are counted per user across watched rooms.

Automod only works while the script is running. If you close it, rooms are unmoderated until you start it again. Use a process manager (pm2 recommended) to make it run 24/7

Set up the account

  1. Register an account on the server you want it to watch. Bot mode is per server, so an automod on your-server.divcord.gg does not run on the main site.
  2. Make that account a room moderator (or a server admin) in every room it should police.
  3. Open Settings and choose Enable Bot Mode or Bot token under Account. Confirm with the account password and copy the token. It is only shown once.
You can still use the automod account in the browser. If the account is not a moderator in a room, or a server admin, it cannot delete, mute, kick, or ban.

Download and run

You need Node.js on the machine that will keep the bot online. Download the library and the automod script from any Divcord host: 

curl -O https://divcord.gg/bot/index.js
curl -O https://divcord.gg/bot/automod.js
npm install socket.io-client

Create a token from the command line if you prefer that to Settings:

DIVCORD_SERVER=your-server \
DIVCORD_USERNAME=automod \
DIVCORD_PASSWORD='your-password' \
node automod.js --enable

Then start it. Put each setting on its own line, with no spaces around =.

DIVCORD_SERVER=your-server \
DIVCORD_USERNAME=automod \
DIVCORD_BOT_TOKEN=dcbot_... \
DIVCORD_ROOMS=general \
node automod.js

When it is up you will see that it signed in, which rooms it is watching, and Automod ready. Leave that window open (or run it under whatever process manager you already use).

Keep the token private. Anyone with it can act as that account. If it leaks, rotate it from Settings and start the script with the new value.

Settings you pass in

These are environment variables: values the script reads when it starts. The name is DIVCORD_BOT_TOKEN, not DIVCORD_TOKEN.

NameRequiredWhat it is
DIVCORD_USERNAMEyesThe registered account
DIVCORD_BOT_TOKENyes*Token from Settings or --enable
DIVCORD_PASSWORDfor --enableThat account's password
DIVCORD_SERVERnoServer name. Use default or omit it for divcord.gg. Use your-server for your-server.divcord.gg.
DIVCORD_URLnoOnly if you self-host and need a different origin
DIVCORD_ROOMnoOne room. Defaults to general.
DIVCORD_ROOMSnoComma-separated rooms, or all for every public room
DIVCORD_PREFIXnoCommand prefix. Defaults to !
DIVCORD_AUTOMOD_CONFIGnoWhere to save live settings. Defaults to a file next to the script.
DIVCORD_AUTOMOD_LOGnoSet to 0 to hide action logs

* You can log in with DIVCORD_PASSWORD instead of a token. A token is the usual choice.

Filters

Turn any of these off in chat with !automod filter <name> off.

NameWhen it fires
blocklistA built-in slur list, plus words you add with !automod word add
flood6 messages from one person in the same room within 8 seconds
duplicateThe same text (4 or more characters) 3 times in 45 seconds
caps12 or more letters, and at least 80% of them uppercase
linksMore than 3 web links in one message
zalgoHeavy accent stacking, or one character repeated 15+ times
uploads10 files from one person within 1 hour, counted across watched rooms. Each attachment on a message counts as one file.

Messages that start with the command prefix are left alone so staff can still type commands. File counts are recorded as soon as a message with attachments arrives, even if another filter already handles that message. The uploads strike only fires when no earlier filter hit.

Strike ladder

Strikes are counted per username, across the rooms automod is in. They expire after one hour.

  1. Delete the message and warn (strikes 1 and 2).
  2. Delete and mute for 5 minutes (strike 3). Automod unmutes when the 5 minutes are up.
  3. Delete and kick (strike 4).
  4. Delete and ban (strike 5 and later in that hour).

A short cooldown stops a flood from jumping the whole ladder in one burst. If mute, kick, or ban is not allowed in that room, automod still tries to delete the message and says so in chat.

When the hit is a blocked word, the room notice shows a censored form (first and last letter only). The uncensored word is sent to that person in a private message. Other filter reasons stay visible in the room.

Who is skipped

  • The automod account
  • The room owner
  • Room moderators
  • The server owner
  • Anyone added with !automod exempt add <user>

Commands in chat

The prefix defaults to !. !am is a shortcut for !automod. Only the people listed above can run these.

CommandWhat it does
!automod helpList subcommands
!automod statusOn or off, which filters are live, how many custom words
!automod on / offPause or resume filtering
!automod filter <name> on|offToggle one filter
!automod word add|remove|listCustom blocklist
!automod exempt add|remove|listExtra people the filters ignore
!automod strikes <user>Hits in the current hour
!automod clear <user>Reset that person's ladder
!automod kick|ban|mute <user> [duration]Act on someone in this room
!automod unmute|unban <user>Lift a mute or ban early
!automod wipe [user]Delete that person's messages in this room, or every message if no user is given

Kick, mute, ban

Only room moderators, the room owner, and server admins can use these. Automod then performs the action as its own account, so that account still needs permission in the room. 

!automod mute noisyuser 10m
!automod kick alice
!automod ban bob 1h
!automod unmute noisyuser
!automod unban bob

Duration looks like 30s, 10m, or 1h. A number with no unit is minutes. Mute defaults to 5 minutes if you omit it. Kick ignores duration. Ban is permanent unless you pass a duration, in which case automod unbans when it runs out.

!automod wipe alice deletes Alice's messages in the current room. !automod wipe with no name deletes every message in that room. Private threads cannot be wiped.

Saved settings

The first time someone changes a setting in chat, automod writes a small JSON file next to the script. Filter toggles, extra words, and extra exempt users come back after a restart. Strikes and the 5 minute unmute timer do not. Those live only in memory and start over when the process stops. If automod restarts during a mute, a moderator can unmute by hand.

How to enable bot mode and write your own bot is on Bot accounts.