Docs

Getting started

Click Dashboard at the top of this page. Discord asks you to confirm who you are, and then you pick a server. The bot's /dashboard command also answers with a private link that signs you in. You need Manage Server to change settings. Each page in the sidebar is one feature. Most features do nothing until you set them up. The bot keeps recent message text for the deleted and edited message logs, 30 days unless you change it.

Move the bot's role above every role you want it to hand out. Discord doesn't let a bot give or take a role at or above its own.

Proposals

A proposal is a change to the server put to two votes on one post. A moderator submits it with /submit_proposal or from the Proposals page. The bot posts it, opens a discussion thread and adds the two vote reactions.

Members have the voting time set on the page, 72 hours unless you change it. Their vote passes if more than half of the votes are in favor. Moderators vote with the same reactions, counted apart, with no deadline. Their vote is decided once more than half of all moderators agree. A proposal is approved only if both votes pass, and it's rejected as soon as either one fails.

Once the member vote is over, moderators who haven't voted get a DM every 24 hours until their vote is decided. /proposal promote or Put to a vote on the Suggestions page starts a proposal from a suggestion, and the result becomes that suggestion's decision.

Role rules

A role rule adds or removes roles for members who match all of its conditions, up to ten. A condition looks at a set of roles: whether a member has any of them, all of them, none of them, or is missing one, or how many of them they hold. Rules run from the top of the list on the Role rules page, and a change one rule makes can set off the rules below it.

A rule that keeps in sync takes its added roles back from members who stop matching, unless another rule that matches them adds the same role. Without it, a role stays until something else takes it. /rolerule create makes a rule that keeps one target role on everyone who holds any of the tracked roles, with an optional ignored role that keeps people out and a required role they must also hold.

The bot looks at a member when their roles change and when they pass the rules screen, at everyone when a rule is saved or switched on, and at everyone again every 10 minutes. Each member gets one role edit for all of their changes, and edits go out at about one a second. Preview on the page shows who would gain and lose each role before you save, and a save that changes more than 200 members asks you to confirm the count. Rules that keep undoing each other's changes are switched off, and so is a rule that checks for a role someone deleted. The server log channel says which ones.

/mass_mention pings every member who holds all of the roles you name, up to 1,000 of them, and asks first when it's more than 50. It needs Mention Everyone, and the roles named in its first line don't ping.

How commands work

Most commands work three ways: as a slash command, after the server's prefix (!warn @someone spamming), and after mentioning the bot. A command listed below with ! in front has no slash form.

A command needs its Discord permission, shown beside it below. A group whose subcommands differ says Varies, and each subcommand shows its own. On the Commands page you can grant bypass roles per command, so a moderator role can use a command without holding that permission in Discord. The same page limits a command to chosen channels or roles, turns it off, or sends its output somewhere else.

A command marked Staff, Moderators or Veterans checks for that group itself, and the group is set on that feature's page. A bypass role doesn't open it.

The bot manager role counts as holding every permission, Ban Members included. Only the server owner or an Administrator can set it, or any other role that makes people staff. To add a bypass role, you need the permission it skips, and the role has to sit below your highest. @everyone can't hold any of these. Manage Server and Administrator skip channel and role limits. A turned-off command is off for everyone, except that /dashboard and /my_data always work, and the owner and Administrators always keep /config.

Settings by page

Each page in the sidebar holds its own settings, and most explain themselves there. These change how a feature behaves. You need Manage Server to change them.

New Twitch alerts go to the channel the command is used in. !twitch default_channel sets another one.

Your data

Any member can type /my_data for a private link to a page that shows what the bot holds about them, gives them a copy, and deletes what's theirs to delete.

The Backup page exports everything stored for a server as one file and can put it back. Scheduled snapshots stay on the server. The Activity page shows who changed which setting, with undo.

Text shortcuts

These short names work when you type a command with the server's prefix. Each one runs the longer command under the same rules.

A word a typed command can't use is refused with the command's usage, and nothing changes. These commands also take text straight after their name:

Commands

Config

Automod

Feeds

Fun

Greetings

Levels

Logging

Misc

Moderation

Roles

Stats

Notifications

Suggestions

Tags & Triggers

Utilities

Embeds

Starboard

Sticky messages

Games

Template language

Tags, triggers, greetings, level-up messages and any other message a server writes can hold blocks. A block is a small instruction in curly braces. The bot replaces it with a result when the message goes out, so Welcome, {user}! greets each person by name.

How a template runs

A block has a name, and sometimes a parameter in parentheses and a payload after a colon: {name(parameter):payload}.

Blocks run from the inside out and left to right, and each result takes the block's place in the text around it. An outer block therefore reads what its inner blocks produced, and a later block can use a variable an earlier one set.

Every complete block runs, even inside the branch of an if that isn't taken. To make a block depend on a condition, put the condition inside the block. The second example below shows the other way to do it, which builds the block's name with an if.

A name nothing answers to stays as written, and so does a block that can't work with what it was given, such as math on a word. Spaces and blank lines at the very start and end of the result are removed. Block names ignore capitals. Variable names don't.

Text from outside the template is data. What a member typed, a nickname or a channel's name can fill in a value, but its punctuation can't change what a block does. Someone typing x==x can't pass a check against a passphrase, and someone typing cmd:ban me can't turn {{args}} into a command block. A name built from outside text can only read a variable.

Where blocks work

Tags and triggers run everything in this reference. In greetings and other messages a server writes, the blocks under Actions and Commands do nothing and leave no text behind, because no one ran them. Embed blocks work everywhere.

Text assigned in a message's text is there for its embed too, so a variable can hold a sentence the embed's title and description both use. An embed's parts run in the order they're shown on the page: author, title, link, description, fields, image, thumbnail, footer.

What the examples assume

Every example in this reference runs against these values, and an automated test checks each one against the bot, so the results shown are the results you'd get.

Variables

Assigning

{=}, {assign}, {let} and {var} all do the same thing: they store the payload under the name in the parameter and leave no text. Read it back with the name in braces. A variable can have any name, but a block's name goes to the block first, so give variables names of two letters or more.

A name can be built from other blocks, and an empty name is allowed. {=():} gives {} something empty to answer with, which is what makes a block's name that sometimes comes out empty safe to use.

Reading part of a variable

Any variable holding text can be read a piece at a time, with a position in parentheses. Pieces are split on spaces, or on whatever the payload says. 1 is the first piece, 0 is the last and -1 is the one before it. A plus sign after the number means that piece onward, and before it means up to that piece. A position past the end gives the whole value, and a span past the end gives nothing.

People

{user} is the person using the tag. {target} is the first person they mention after the tag's name, or the same person when they mention nobody. On their own, both give the display name. In a trigger, the target comes from the message's mentions. In a role trigger, {user} is whoever changed the role and {target} is the member it changed on. Its require, blacklist, dm and command blocks act for that member.

The server

The channel

The role, in role triggers

Conditions

A condition compares two sides with an operator. == and != compare text exactly, capitals included. The others compare numbers.

In a block with an else, a pipe divides the payload: what's before it comes out when the condition holds, and what's after it when it doesn't. With no pipe, a condition that fails gives nothing. With two or more pipes, the whole payload comes out when it holds.

Lists

{list}, {cycle} and {random} read a list split on tildes when there are any, otherwise on commas. Use tildes when an element holds a comma. Counting starts at 0, and a negative number counts back from the end.

Text

Math

{math}, {m}, {+} and {calc} all work out the expression in their payload, in the usual order of operations. Numbers are decimal, so {m:2+2} gives 4.0. Only trunc, round and sgn give whole numbers. An expression that can't be worked out stays as written.

Random

{random}, {rand} and {#} pick from a list split on tildes or commas. An element written 4|text counts as four copies of that element. Give a seed in the parameter and the same seed picks the same place every time, which is how a tag can give each person a fixed result: {random({user(id)}):Mage,Warrior}. The same seed on a list of another length can land on a different element.

Time

All times are UTC. A date is written yyyy-mm-dd HH:MM:SS, and periods work in place of the colons. A number means seconds since 1970.

The format codes are the ones on Linux, in English, and the same on every server.

Actions

These blocks leave no text behind. They ask the bot to do something when a tag or trigger runs. The order is fixed: require and blacklist decide first, then the output goes out, then reactions, then commands, and the delete comes last.

Embed blocks

These change the first embed the message has, and a message with no embed gets one.

Commands

A command block runs one of the bot's commands, written as you'd write it after the prefix, short names included. The output of the tag goes first. Command blocks can't run tags or the tag and reaction role commands, and each tag runs at most five. If the person can't use the command, they get the same error the command would give them.

A tag or trigger starts out untrusted. A tag's command blocks then only run for its owner, nothing in its output pings anyone but the person it moves to the bot channel for, and automod reads what it's about to post. A trigger's command blocks don't run at all, and it only reads and posts in channels whoever wrote it can, so it goes quiet if they leave. The server owner or an Administrator can mark either one as trusted on its page, and it stops being trusted if anyone else changes its text or who can use it. Anyone else who changes a tag's text also becomes its owner, so its command blocks run only for whoever wrote the words.

What a trusted tag or a trigger posts can ping the person who set it off, the person they named, and anyone its own text mentions. Text a member typed pings nobody else.

Since every complete block runs, an if around a command block doesn't stop it. Put the condition inside, or build the block's name with an if as below.

A worked example

This tag greets whoever is mentioned, in an embed, using a random color for anyone whose color is the default, and gives them a role. Its text comes out empty, because every line is a block that leaves nothing.

{=(hello):Welcome aboard, {target(mention)}. You're part of {server} now.}
{=(oops):Mention the person you want to greet.}
{embed(description):{if({user(id)}!={target(id)}):{hello}|{oops}}}
{=(digits):0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F}
{=(shade):#{#:{digits}}{#:{digits}}{#:{digits}}{#:{digits}}{#:{digits}}{#:{digits}}}
{embed(color):{if({target(color)}==#000000):{shade}|{target(color)}}}
{=():}
{{if({user(id)}!={target(id)}):cmd:role add {target(id)} Crew}}
{silent}

The next tag reads a small table of holidays. Each variable holds three values with pipes between them, and the name comes from what the person typed.

{=(one):Christmas|December 25|a tree}
{=(two):Valentine's Day|February 14|a heart}
{any({1}==one|{1}==two):{{1}(1):|} falls on {{1}(2):|}. Look for {{1}(3):|}.}

Christmas falls on December 25. Look for a tree.

Limits

No template can hang the bot or fill the channel. A run that goes past a limit stops: a tag or trigger then posts nothing and does nothing, and other messages go out with the template left as written.

A server's tags, its triggers and its other messages each have 5 seconds of processing time a minute, and one person has 1 second a minute across all of them. Past either, a tag or trigger does nothing until the next minute, a tag typed in chat gets a warning reaction, and other messages go out with the template left as written.

A tag or trigger that uses its whole 0.25 seconds is stopped for 10 minutes. It stops for everyone when its owner ran it, or once three different people have run it that far. Otherwise only the same text after its name stays stopped. A tag's owner gets a DM and a trigger leaves a note for staff. Changing the words turns it back on.

What comes out gets cut to what Discord accepts: 2,000 characters of text, 4,096 for an embed's description, 6,000 across a message's embeds. A link that doesn't come out as a link is dropped, and so is an embed field left empty, because Discord refuses a whole message over either.