Introduction

Donkcord is a Discord bot with a web panel. Most things can be done either with a slash command in Discord or from the panel, and a few things (DonkGuard, logging, integrations, the embed builder) only live in the panel.

These docs go through each module: what it does, how to set it up, and the commands that belong to it. If you just want to get going, start with Adding the bot and then Using the panel.

Where things are

The panel sidebar is split into the same groups used here. Moderation covers the day to day stuff (warns, mutes, bans, the audit log). Utility is where welcome messages, tickets, starboard and the other community features sit. Tools has the embed builder, reactions, integrations and the scheduler.

Getting help

If a command replies with a permission error, check Permissions first. Almost every problem people run into comes down to the bot's role sitting too low in the role list, or the bot missing a channel permission.

Adding the bot

You need Manage Server on a server to add Donkcord to it.

Click Add to server at the top of this page, pick the server, and keep the permissions ticked. The invite asks for everything the bot uses: managing messages, roles, channels, webhooks and threads, plus kick, ban and timeout.

If you are already signed in to the panel, the same link is under your avatar menu as Add to a server.

After inviting

• Open Server Settings, Roles and drag the Donkcord role above every role you want it to manage. It cannot give, remove or punish anyone whose top role is at or above its own.
• Slash commands show up on their own. If they don't appear within a minute, restart your Discord client.
• Sign in to the panel with Continue with Discord and pick the server.

Using the panel

The panel is the website you sign in to with Discord. It shows every server you share with the bot where you have mod permissions.

To sign in you need at least one of Manage Messages, Moderate Members, Ban Members or Administrator in a server the bot is in. Pick a server from the dropdown at the top of the sidebar to switch between them.

Pages

Anything that takes a member has a search box. Type part of a username or nickname and pick from the list, or paste an ID. Discord only matches from the start of a name, so ben finds "benny" but nny won't.

Timezone

Times in placeholders like {time} and {date} use the server's timezone, which defaults to UTC. Change it on the Scheduler page.

Permissions

Two things are checked for every action: whether you are allowed, and whether the bot is able.

For slash commands

Each command lists the Discord permission it needs on its page. Administrator always passes. Server admins can also change who sees a command under Server Settings, Integrations, Donkcord, but the bot still checks the permission itself when the command runs.

For the panel

Anyone with one of Administrator, Ban Members, Kick Members, Moderate Members, Manage Messages or Manage Channels can open a server in the panel. Some pages need more than that:

Voicemail boxes need Administrator, Manage Server or Manage Channels. Removing the bot from a server is limited to the server owner and Administrators, and you have to type the server name to confirm.

Role hierarchy

You can only give or take roles that sit below your own highest role, and the bot can only touch roles below its own. The role autocomplete in commands only lists roles that pass both checks.

Moderation commands

The basic set. Every action is recorded as an infraction and shows up on the member's history.

/mute takes minutes, up to 40320 (28 days, Discord's limit). To ban someone who isn't in the server, paste their user ID into the user option. The panel's ban takes an ID the same way. They won't get a DM, since the bot can't message people it doesn't share a server with.

From the panel

The Commands page and the Members page run the same actions. Actions taken there use the DM and mod log settings from Mod log.

Warnings and punishments

Warnings add up. You can set what happens when a member reaches a certain number.

Punishments

Times are written like 30m, 2h, 7d or combined, 2d12h.

Role commands

Give, take and edit roles. All of these need Manage Roles, and the role has to be below both yours and the bot's.

Every role option autocompletes. You can also type the role's name, paste an ID, or @mention it.

Mod log

Found under Moderation in the panel. Controls where panel actions get posted and what the member is told.

Manage Server

• Mod log channel gets an embed for each action you pick: warn, mute, unmute, timeout, untimeout, hardmute, kick, ban, tempban, softban and unban.
• DM can be set per action. None sends nothing, Action tells them what happened, Full adds the reason and who did it. Warns, mutes and timeouts default to Full, everything else to None.
• Mute role is used for hardmutes, where a role is given instead of a Discord timeout.
• Defaults are the prefilled durations: timeout 60 minutes, and how many days of messages a ban or tempban deletes.

Superpurge

Deletes every message one person sent, across the whole server or in one channel.

Manage Messages

It's on the Commands page. Search for the member or paste their ID, pick a channel or leave it on the whole server, and optionally set a date range.

• Threads are included by default. Archived threads are opened, cleaned and archived again.
• Discord only bulk deletes messages under 14 days old. Anything older goes one at a time, so a big cleanup can take a while. It keeps running on the bot if you leave the page.
• One superpurge per server at a time. Cancel stops it where it is.

DonkGuard

The bot's own automod. It reads every message and acts when one breaks a rule you turned on.

Manage Server

Each module has its own switch, its own actions and its own DM text. When a message trips more than one, only the first one in this list counts.

Actions

Pick any mix. They always run in this order: delete, DM, warn, timeout, mute, kick, softban, ban.

• Timeout, mute and ban use the module's duration. Mute gives the mute role from General, and with a duration it's removed later. Ban with a duration unbans later.
• Warn adds a normal warning with the reason "DonkGuard: ...", so your warning punishments still apply.
• DM sends the module's DM text. It takes the same placeholders as custom reactions.

General

• Log channel gets an embed for every hit.
• Immune roles and ignored channels are skipped. Ignoring a category covers the channels inside it.
• Media channels only allow posts with an attachment or a link. Plain text gets deleted.
• Delete risky files removes executables and scripts (exe, bat, scr, msi, jar, apk, ps1 and so on). You can add your own extensions.

Discord AutoMod

A panel for Discord's built-in AutoMod rules, the same ones under Server Settings, Safety Setup.

Manage Server

These run on Discord's side, so they block a message before anyone sees it. DonkGuard can only delete after it's posted. Use this for hard blocks and DonkGuard for anything that needs counting over time or a punishment.

Actions are block the message, send an alert to a channel, and time the member out. Each rule can exempt roles and channels.

Logging

Posts server events to channels you pick. Everything starts off, so turn on what you want.

Manage Server

There's a default channel plus optional channels for messages, members, server, voice and joins/leaves. An event goes to its own channel if you set one, otherwise the default.

Log entries have buttons to copy the user ID and jump to the message. Where Discord's audit log knows who did something, the moderator is shown too. You can ignore channels (or whole categories) and roles.

Welcome and join roles

Greet new members, DM them, and hand out roles when they join.

Manage Server

Join roles

Up to 10 roles for people and a separate list of up to 10 for bots. A role gets skipped if it's above the bot's own role, managed by an integration, or deleted.

Welcome message

Pick a channel and write the message. It can be plain text or an embed with a title, colour and the member's avatar as the thumbnail. You can have it deleted after a number of seconds, and choose whether the new member gets pinged.

Welcome {user} to {server}. You are member number {server.membercount}.

Welcome DM

Sent privately. Members with DMs closed just don't get it.

Thanks for joining {server}. Read the rules in {#rules} and say hello.

Both take every placeholder and condition. {user} is the new member. Send a test posts the welcome message to the channel with you as the new member.

Bots are skipped for messages by default, but still get the bot roles.

Starboard

When a message gets enough of a reaction, it's reposted to a starboard channel.

Manage Messages

You can also ignore channels, pick the embed colour, and choose whether attachments show.

Tickets

A button in a channel that opens a private thread between the member and your staff.

Setting up a panel

• Panel channel is where the button goes.
• Ticket channel is where the private threads get made. The bot needs Create Private Threads there.
• Staff roles are the only ones, besides admins, who can resolve or close a ticket. Only the member who opened it is added to the thread, so give staff Manage Threads in the ticket channel or they won't see new tickets.
• Log channel gets a record when a ticket is closed, and notify channel gets pinged when one opens.
• Max open is how many tickets one member can have at once. Default 1.

The panel message can be plain text or a full embed. When someone presses the button they get a short form: subject, details, and an optional sub-category. You can rename these fields, change their hints, or turn them off.

Closing

Inside the ticket there's a Resolve and a Close button. Either one asks for a reason, posts the result, sends it to the log channel and deletes the thread a few seconds later.

Transcripts

Set Transcript on the panel and the whole ticket is saved as a file and attached to the close message in the log channel. Each panel picks its own format.

Transcripts need a log channel, and the bot needs Attach Files there. Images in a transcript point at Discord's copies, which stop loading after a while, so save anything you need to keep. Very long tickets are trimmed to fit Discord's upload limit, and the file says when that happened.

Submissions

A form members fill in from a button. Each entry is posted to a channel.

Build the form with up to five fields, short or paragraph, required or not. One field must be the link field (this is meant for things like clip or art submissions), and you can mark another as the message.

Entries post as "Submission from name" with the message and link, and a button to submit again.

Reading entries from your own site

Create an API token on the panel. Tokens are shown once, so copy it then. Then:

GET /api/ext/submissions?token=dk_yourtoken

You get back a list with the submitter's name, message, link, whether it's been viewed, and when it came in. A token only sees entries from the last so many days (you choose, up to 365) and can have an expiry date.

Voicemail

A channel that only takes voice messages, with limits on how often people can post, and an optional public page to listen back.

Manage Channels

Point a box at a channel. Anything that isn't a single recorded voice message (text, files, stickers, polls) is removed, and the member can be told why.

Limits

• Off: post as often as you like.
• Cooldown: one message per member every so often. A week by default.
• Deadline: a set number of messages per window, and the window resets daily, weekly, every two weeks or monthly.

You can also set a minimum and maximum length, and who can post, who can only listen, and who skips the rules. Turn on manage permissions and the bot sets the channel overwrites for you.

Feed

The feed is a page at /v/your-name that plays the messages in order. Pick a title, colour and page size, and whether names and downloads are shown. From the panel, staff can star, hide or archive messages and leave notes.

Cooldown messages can use {user} and {when}, and the confirmation can use {user} and {duration}.

Custom reactions

The bot replies when someone says a trigger word. Replies can be text or embeds, can take arguments, and can have buttons.

Reactions don't use a prefix. If you want !rules, make the trigger !rules.

Commands

The panel has everything else: full embeds, buttons, role and channel limits, cooldowns and so on.

Matching

Matching ignores case. Only one reaction fires per message.

Arguments

Words after the trigger are arguments. $1 is the first, $2+ is everything from the second on, and $* is all of it. If an argument is a member (a mention or an ID), you can read their details with $1.user.name, $1.user.joinedat and so on. The full list is on Placeholders.

Set Required args and the reaction won't fire until that many are given.

Trigger:  !hug
Match:    Starts with
Response: {user} hugs $1.user.mention{if:$2} because $2+{endif}

Options

• Allowed and ignored roles and channels decide where it works and for who. Allowing a category covers its channels.
• Cooldown is per member, up to 10 minutes.
• Delete trigger removes the message that set it off. Delete after removes the reply after some seconds.
• DM response sends the reply privately. Response channel sends it somewhere else.
• Allow @everyone lets {everyone} and {here} actually ping. It needs Manage Server to turn on.

Modifiers

You can put these anywhere in the response. They change how it behaves and are removed from what gets posted.

Examples

New servers get five example reactions: !banr, !roles, !whois, !serverinfo and !8ball. They're off until you turn them on, and you can edit or delete them like any other. !banr is a good one to read through: a mod files a ban request and the card has Approve and Deny buttons.

Each reaction has Duplicate and Export buttons. See Import and export.

Embed builder

Write a message with up to 10 embeds and 5 buttons, see it as it'll look, and post it.

Manage Messages

Each embed has an author, title, link, description, colour, thumbnail, image, fields (up to 25), footer and timestamp. There's a message body above the embeds too.

Posted messages are saved. Open one later and you can edit it in place, copy it to another channel, or delete it. Deleting in the panel asks whether to remove the Discord message too.

Placeholders

Server, time, random and mention placeholders work, and so do conditions. Since nobody triggers an embed, {user} is you, the person posting it, and {channel} is where it's going.

Messages can be exported to a file, imported back, or duplicated.

Buttons

Buttons can go on custom reactions, integration replies and messages from the embed builder. Up to 5 per message.

Kinds

• Link buttons open a URL. Nothing else to set up.
• Script buttons run a short script when pressed. The script uses the script directives.

Each button has a label, a colour (grey, blue, green or red), a per-member cooldown, and a list of roles allowed to press it. Leave roles empty and anyone can.

What a button can run

Any script button can give and remove roles and post announcements. Punishment commands (warn, mute, unmute, kick, ban, unban) and channel commands (slowmode, lock, unlock) only work once you've set roles on the button. Otherwise anyone could press it.

Who pressed it

Inside a button script, {clicker.*} is the person who pressed it. {clicker.mention}, {clicker.id}, {clicker.rolenames}, {clicker.isadmin} and the rest are on Placeholders. You also get {message.link} and {button.label}.

Buttons on reactions

On a custom reaction, $1, $2+ and $1.user.* are filled in when the reaction is posted, so the button remembers the arguments. {clicker.*} is filled in later, when someone presses it. That's how a ban request can carry the target and the reason through to whoever approves it.

{require:clicker.id == 123456789012345678}
{run:ban $1.user.id {if:$2}$2+{else}Ban request approved{endif}}
{edit:Ban request for $1.user.tag approved by {clicker.mention}.}

If someone else presses it, {require:} stops the script. To tell them why, branch instead:

{if:clicker.id != 123456789012345678}
{reply:Only the owner can approve this.}
{stop}
{endif}
{run:ban $1.user.id $2+}
{edit:Ban request for $1.user.tag approved by {clicker.mention}.}

What the presser sees

After a button runs, the person who pressed it gets a reply only they can see. By default it says what happened. Use {reply:text} to write your own.

Scheduler

Run things later, or over and over.

From Discord

Times here are a number and one unit: 30s, 10m, 2h, 1d, 1w. Repeats have to be at least a minute apart.

From the panel

The panel does a lot more. A task has a schedule and up to 10 actions.

Placeholders work in scheduled messages, but nobody triggered them, so {user} is the bot and $1 is empty. Run now fires a task straight away without changing its schedule.

Integrations

A command that calls an API and posts what comes back. Weather, stats, a game server's player count, anything with a URL.

Manage Server

Integration commands use the ! prefix. An integration with the trigger weather runs on !weather london.

Request

• Method and URL. GET, POST, PUT, PATCH or DELETE. The URL has to be a public address.
• Headers, up to 20.
• Body as JSON, form data or plain text.
• Timeout, 30 seconds by default, 2 minutes at most.

$1, $2+ and $* can go in the URL and body. So can {user.id}, {server.id} and the rest of the placeholders.

https://api.example.com/weather?city=$*&units=metric

Secrets

Save API keys under Credentials and use them as {secret.NAME} in headers, the URL or the body. They're stored encrypted and never shown again after you save them.

Authorization: Bearer {secret.WEATHER_KEY}

Response

Set a response path to pull one field out of JSON, like data.current.temp or results.0.name. Then write the reply with {resp.*}:

It's {resp.current.temp} degrees in {resp.location.name}. ({resp.ms}ms)

There's a separate error template for when the call fails. The reply can be text, an embed, or an image if the API returns one, and it can go as a reply, to a set channel, by DM, or nowhere. Integration replies can have buttons.

Like reactions, integrations have role and channel limits, a cooldown, and a required argument count with a usage hint.

Run test calls the API with the arguments you type and shows the response. Click a field in it to make it the response path.

Incoming webhooks

A URL other services can send data to. A short script decides what the bot does with it.

Manage Server

Create one under Integrations and you get a URL like https://your-panel/hooks/abc123.... Anything that can send a POST (GitHub, a form service, your own server) can use it. Up to 3 per server.

The script

The incoming body is {payload}. Reach into it with dots: {payload.repository.full_name}, {payload.items.0.id}. Headers are {headers.name}.

{require:payload.action == opened}
{not:payload.pull_request.draft}
{post:#dev} New PR in {payload.repository.full_name}: {payload.pull_request.title}
{post:#dev} {payload.pull_request.html_url}

Every directive is on Script directives. Paste a sample body in the panel and hit Preview to see what the script would do without doing it.

Signing

Set a signing secret and the bot will reject anything not signed with it. It checks an HMAC-SHA256 of the raw body in X-Hub-Signature-256, X-Signature-256 or X-Signature, with or without sha256= in front. That's the same format GitHub uses, so for GitHub just paste the same secret in both places.

Each URL takes 60 requests a minute and bodies up to 256 KB.

Import and export

Move reactions, integrations and embeds between servers, or keep a backup.

Reactions, Integrations and the Embed builder each have Export and Import at the top. Export saves everything on that page to a JSON file. Each item also has its own Export for just that one, and Duplicate to make a copy you can change.

When importing, pick what to do with items that already exist: skip them, or replace them. Reactions are matched by trigger, integrations by trigger and then name.

• Duplicates start switched off. Imported items keep whatever on or off state they were exported with.
• Imported webhooks get a new URL and no signing secret, so update whatever sends to them.
• Credentials are never exported. Add them again on the new server.
• Embed imports load into the builder so you can check them before posting.

{
  "donkcord": 1,
  "kind": "reactions",
  "items": [
    { "trigger_text": "!rules", "match_type": "word", "response_type": "text", "response": "Read {#rules} before posting." }
  ]
}

Placeholders

Words in braces that get swapped for real values when the message is sent. They aren't case sensitive.

Custom reactions, welcome messages and DonkGuard DMs get the full set. The embed builder, ticket and submission panels and scheduled posts get everything except the member ones, since nobody triggered them. Button and webhook scripts have their own set, further down.

Member

Server and channel

Arguments

Reactions only. These don't take braces.

Mentions

In any message box in the panel you can type @ to search members and roles.

Random and time

Times use the server timezone. Wrap {timestamp} in Discord's format to get a time that shows in each reader's own timezone: <t:{timestamp}:R>.

In button scripts

In a button script {user} also means the person who pressed it.

In webhook scripts

{payload.*} for the body, {headers.*} for headers, {hook.name}, and {server.name}, {server.id}, {server.membercount}. Headers carrying keys or signatures are hidden. There's no channel, since nothing was posted.

Conditions

Show different text depending on who, where or what. Works everywhere placeholders do, including buttons and webhooks.

{if:user.name == sam}Hey Sam.{elseif:$1}You said $1.{else}Hi {user}.{endif}

A block starts with {if:test}, can have any number of {elseif:test}, one {else}, and ends with {endif}. Blocks can be nested.

Tests

You can leave the braces off the left side. {if:user.name == sam} and {if:{user.name} == sam} are the same. Arguments work too: {if:$2} checks whether a second word was given.

{if:clicker.rolenames ~ Moderator}
Welcome back, mod.
{else}
This one's for mods.
{endif}

When a tag sits on a line by itself, the line break goes with it, so you can lay blocks out over several lines without leaving gaps in the message.

In a button on a reaction, a test that uses {clicker.*} is left alone when the reaction posts and checked when the button is pressed.

Script directives

Button and webhook scripts are a few lines, run top to bottom. A line that starts with a directive does that thing. Any other line is posted as a message.

Lines starting with // are skipped, so you can leave yourself notes. A script can post up to 10 times and run up to 5 commands.

Commands for {run:}

A user can be an ID or a mention. On a button, everything past setrole, removerole and announce needs roles set on the button first.

Channel monitor

Watch a channel live from the panel and post into it as the bot.

Messages show up with the formatting, replies, embeds and attachments you'd see in Discord, starting with the last 100. You only see channels you can see in Discord.

Posting needs Manage Messages and Send Messages in that channel. Deleting a message from the monitor needs Manage Messages.

Archive and viewer

Save a whole channel to a file, then read it back later in the panel.

Manage Server

Text channels, announcement channels, threads and voice channel chats all work. The finished file is a .jsonl, one message per line. The download link only lasts a few minutes, so grab it when it's ready.

Viewer

Open the file on the Archive page. It's read in your browser and never uploaded. You can search, filter by member and date, and narrow down to images, files, links, embeds, replies, edited or pinned messages. Clicking a reply jumps to the original.

Site embeds

Put a live Discord channel on your own website. Visitors read it, and if you allow it, sign in with Discord and post.

Manage Messages

Each embed gives you a snippet to paste into your site. Up to 3 per server.

Who can see and post

• Viewing: anyone, anyone signed in, server members, people who can see the channel in Discord, or certain roles.
• Posting: anyone signed in, members only, certain roles, or guests. You can also set a minimum account age and block users.
• Allowed sites: the domains it's allowed to load on. *.example.com works.

Posts from the site show up in Discord through a webhook named after the poster, name (web) by default. They go through the embed's own word filter and DonkGuard if you turn it on, and you can set a cooldown, a per-minute limit and a max length.

Looks

Light, dark or match the visitor. Accent colour, background, spacing, font size, corner radius, which parts of messages show (avatars, times, images, embeds, replies), and what the lock screen says when someone isn't allowed in.