Discord

The SuperMDT bot connects your organization to your Discord servers. Once linked, a server:

• gives service and rank roles to your members, and removes them when they change rank or leave the service;
• enforces nicknames, if you want, as [Callsign] First Last or your own format;
• posts announcements, leave, sanctions, summons and duty changes in the channels you pick, with messages whose layout you choose;
• answers the commands /duty, /absence, /roster and /profile.

The MDT is the source of truth; Discord mirrors it: ranks and rosters are never managed from Discord. When something changes in the MDT, the bot corrects Discord; the reverse never happens.

Everything is set in Settings › Discord, which only the organization’s administrators and ranks with Delegated administration › Set up Discord can open (see Delegated administration). Every link, unlink and setting (covered services, roles, nicknames, channels, templates, commands) is recorded in the audit log.

Screenshot coming soonstart-discord-home

Settings › Discord: linked servers and your account

Before you start

• You must be an administrator or the owner of the organization, or have the Delegated administration › Set up Discord permission (never given by default).
• On Discord, you need the Manage Server permission on the server to link.
• Use the same Discord account you sign in to the MDT with: otherwise linking is refused.
• Your members are recognized on Discord as soon as they have signed in to the MDT with Discord. The Your account card shows how many have (for example “18 of 24 members have linked Discord”). Nobody is invited into the MDT from their Discord roles: joining always goes through an invite.

Linking a server

1. In Settings › Discord, Servers tab, click Add a server.

2. Tick the Covered services for this server. By default, those without a server yet are ticked; those already covered elsewhere are greyed out (Already on …).

3. Click Continue on Discord. Discord asks you to pick the server and accept the bot’s permissions: keep them all ticked.

4. You come back to SuperMDT with the message Discord server linked. The server opens: the bot reads its roles and channels (a few seconds), then gives the members of the covered services their roles.

Screenshot coming soonstart-discord-add-server

Picking the server’s services before opening Discord

You can also invite the bot from the Invite the bot step of getting started: it covers the services that don’t have a server yet, brings you back to getting started when you return from Discord and shows, live, the bot’s arrival and any missing permissions.

The request stays valid for 15 minutes. If linking fails, a message explains why:

Message	What happened
Adding the bot was cancelled on Discord.	you closed or declined Discord’s window
The request expired: start again.	more than 15 minutes, or link already used
The Discord account used isn’t the one on your MDT account.	you were signed in to Discord with another account
This Discord server is already linked to another organisation.	a Discord server belongs to one organization only
On Discord, pick the server you meant to re-invite the bot to.	when re-inviting the bot, you picked another server than the one in the list
Discord didn’t confirm the bot was added. Try again.	a temporary Discord issue

One server per service, or one for all

An organization can link up to 20 servers. Two approaches, which you can mix:

• one shared server covering all your services;
• one server per service: the police Discord covers the police, the EMS Discord covers EMS, and so on.

The rule: a service belongs to one server only. That server gives its members their roles and receives its posts. A server with no service only receives organization-wide announcements. Below the list, Services without a server lists those covered nowhere.

To change a server’s services, open it, Server tab, Covered services card, then Save services. Removing a service also removes, on that server, the roles SuperMDT managed for its members.

A server’s state

Each server in the list carries a badge:

Badge	Meaning	What to do
Ready	the bot is there with all its permissions	nothing
Not read yet	the bot hasn’t read the roles and channels yet	wait until it is online, or Refresh
Missing permissions	one of the bot’s permissions was removed	Re-invite the bot
Bot removed	someone kicked the bot from the server	Re-invite the bot

At the top of the list, Bot online or Bot offline tells whether the bot responds (it checks in every 5 minutes; with no news for 11 minutes, it shows as offline). When offline, nothing is lost: posts wait in the queue and go out when it returns.

In a server’s Server tab:

• Refresh asks the bot to read roles and channels again (the list also updates by itself when you change roles or channels on Discord);
• Re-invite the bot reopens Discord on that same server, to bring the bot back or restore its permissions;
• Unlink server (hold to confirm): the bot leaves the server. Roles already given and messages already posted stay on Discord.

Roles

A server’s Roles tab. For each covered service, pick:

• the Service role, given to all its members;
• a Role for … per rank, given to those who hold that rank.

Each list filters as you type; roles show with their Discord color. None removes the mapping. A role deleted on Discord shows as Not found on the server: pick another one. A greyed-out role sits above the bot’s role: Discord forbids the bot from giving it (see What you set on Discord).

Screenshot coming soonstart-discord-roles

Mapping a role to the service and to each rank

Roles follow the MDT automatically: when a member arrives through an invite, is assigned, promoted, removed from a service or from the organization, and when they switch character. SuperMDT only touches the roles you mapped: your members’ other roles (friends, streamers, notifications…) never move.

Suspension role (optional): added during a suspension, removed when it ends. The member’s other roles stay in place; it is up to you to set on Discord what this role prevents (hidden channels, for instance).

Resync all members gives every linked member their roles and nickname again. Useful after moving roles on Discord or fixing the bot role’s position.

A member who joins the Discord server later

They get their roles on arrival if the platform has enabled member-join detection (see the end of this page). Otherwise, they get them on the next change in the MDT, or when you click Resync all members.

Nicknames

A server’s Nicknames tab. Enforce nicknames is off by default: when off, SuperMDT never touches nicknames.

When on, every linked member gets the nickname from the Nickname template, kept up to date on every rank, callsign or character change. The default template is [{callsign}] {firstName} {lastName}, which gives “[12] Jordan Miles”. Click a variable to insert it at the cursor:

Variable	Replaced with
{callsign}	the callsign
{firstName} / {lastName}	first name / last name
{name}	the full name
{grade}	the rank
{service} / {serviceShort}	the service’s name / short name

• The name is the roleplay name of the active character when game integration is on, otherwise the account name.
• The nickname uses the member’s main service among the server’s (the first in your services’ order).
• Brackets or parentheses left empty disappear: with no callsign, “[12] Jordan Miles” becomes “Jordan Miles”. The Preview shows both cases.
• Discord caps a nickname at 32 characters: anything longer is cut.
• An unknown variable (a typo) is flagged below the field.

Screenshot coming soondiscord-nicknames

The Nicknames tab: the template, its variables and the preview

The Discord server owner can’t be renamed

Discord doesn’t let any bot change the server owner’s nickname. If that owner is a member of your organization, the Nicknames tab says so: their roles are synced, but their nickname stays the one they chose.

Channels and message templates

A server’s Channels tab. Six posting channels, each turned on separately:

Channel	What is posted there
Announcements	announcements published in the MDT
Absences	leave declared, extended or cancelled
Sanctions and summons	sanctions and summons, mentioning the member concerned
Shift start and end	members clocking in and out
Prosecutor requests	a file’s prosecutor requests, with an Accept button
Public defender requests	a file’s defence lawyer requests, with an Accept button

For each one: pick the Channel (channels the bot can’t post in are greyed out; each channel shows its type, Text channel or Announcement channel, both accepted), then Post in this channel. The optional Role to mention is quoted at the top of each message; a role that can’t be mentioned is flagged.

Screenshot coming soonstart-discord-channels

A server’s channels and their templates

Messages follow the MDT: extended leave edits its message, cancelled leave deletes it; a lifted or expired sanction updates its message, an archived sanction deletes it; an edited or rescheduled announcement too. Shift starts and ends are posted once. The reason for private leave is replaced with “Reason restricted to supervisors”.

Prosecutor and lawyer requests

Screenshot coming soondiscord-counsel-channels

The prosecutor and lawyer request channels

When a member requests a prosecutor or a public defender on a file, the message goes to the Prosecutor requests (or Public defender requests) channel of every linked server that has it on: set it on the server that covers your justice service, or your bar. The Role to mention is pinged at the top of the message: that is what alerts the available prosecutors (or lawyers).

The message gives the file, the defendant, the offences, the place, the request’s status and a link to the file in the MDT. Under the message, an Accept button:

• the click accepts the request with the same rules as in the MDT: the Discord account must be linked to a member who can be a prosecutor (or lawyer); the bot’s answer is only visible to them;
• the first one to accept, on Discord or in the MDT, takes the file; the message is then updated (“Accepted by …”) and loses its button and mention;
• a cancelled or expired request updates its message too.

Where does an announcement go? A service’s announcement goes to that service’s server. An organization-wide one goes to every server whose Organisation-wide announcements switch (Announcements card) is on; it is on by default.

Inherited templates

Each message type (Published announcement, Absence, Sanction, Summons, Shift start, Shift end, Prosecutor request, Lawyer request) has a template, resolved in this order:

1. the template customised on this server, if any;
2. otherwise the organisation template, set on the Settings › Discord home, Templates tab, and shared by every server;
3. otherwise the default template, written in the organization’s language.

In the Channels tab, each template shows its source: Customised on this server, Organisation template or Default. Start by setting the organization templates, then only customise on a server what must differ there.

Screenshot coming soonstart-discord-templates

Organization templates, inherited by every server

The editor and its viewer

Edit opens the editor. Next to the fields, the viewer shows the message as it will appear on Discord, with sample values, and updates as you type.

• Message text: above the embed. This is where a mention ({agentMention}) actually notifies; inside the embed, it is only displayed.
• Title, Description, Footer: the body of the embed.
• Colour: Service colour (falling back to the organization’s accent) or Custom colour as #rrggbb.
• Fields: up to 10, each with a Name, a Value and the Side by side option; the arrows reorder them. An empty field disappears from the posted message.
• Show the event time: the time shows under the embed.
• The variables specific to each message type insert with one click (table below). An unknown variable is left as is and flagged.

The editor header reminds you of the template’s scope: For … only (one server) or For every server that doesn’t customise it (organization template).

Template	Variables
Published announcement	{title} title, {body} text, {author}, {service}, {org}, {date}
Absence	{agent}, {agentMention}, {callsign}, {grade}, {service}, {from} first day, {to} last day, {days} number of days, {reason}, {status}, {org}
Sanction	{agent}, {agentMention}, {callsign}, {grade}, {service}, {type} sanction type, {reason}, {status}, {issuer} decided by, {until} ends, {org}
Summons	{agents} summoned members, {agentMentions} their mentions, {service}, {date}, {place}, {subject}, {issuer}, {status}, {org}
Shift start	{agent}, {agentMention}, {callsign}, {grade}, {service}, {time}, {org}
Shift end	the same, plus {duration} shift length and {endReason} end reason
Prosecutor request, Lawyer request	{file} file number, {defendant}, {offenses}, {place}, {link} link to the file, {requester} requested by, {service}, {status}, {expires} request expiry, {org}

The default templates use these variables: for example “{agent} is away” with the From, To, Status and Reason fields, or {agentMention} as a sanction’s message text (the member is notified).

Screenshot coming soonstart-discord-template-editor

The template editor and the Discord message preview

To go back (hold to confirm): Back to the organisation template on a server, Restore the default template for the organization template. Send a test posts the template with sample values in the chosen channel: handy to check permissions and rendering.

Discord enforces its limits: 2000 characters for the text, 256 for the title, 4096 for the description, 2048 for the footer, 256 for a field name and 1024 for a value. The editor flags them; when posting, text that is too long is cut with “…”.

No surprise mentions

Only the people and the role the template intends are notified. An @everyone or a role mention typed in a reason or an announcement is displayed without notifying anyone.

Slash commands

A server’s Commands tab. Commands are typed in English on Discord; replies follow the member’s language (the one chosen in the MDT, otherwise Discord’s). They only cover the services this server covers, and the member must have linked their account by signing in to the MDT with Discord.

Command	What it does	Permission needed	Visible to
/duty [service]	who is on duty (15 names per service at most), and your own status	Duty › See the team’s hours, or access to dispatch or units	you only
/absence from reason [to] [service]	declare leave, just like in the MDT; dates YYYY-MM-DD or DD/MM/YYYY, to defaults to from	Leave › Declare one’s leave	you only
/roster [service]	a service’s roster: ranks, callsigns, names (25 at most)	Roster › See the roster	the whole channel
/profile	your hours (this week, last week), latest payslip, active sanctions	none	you only

Screenshot coming soondiscord-commands

The Commands tab: each command and its switch

• The relevant module must be on in the service (Duty, Leave, Roster), and the permission is set in the permission matrix. /profile only shows pay with the Payroll module, and sanctions only if the service has turned on Members see their own sanctions.
• Leave declared with /absence follows the service’s rules: it may wait for approval, and a suspended member can’t declare any.
• If you are in several services, pass the service: Discord suggests the list.
• No command looks up a record, plate or warrant. Files stay in the MDT.

Turning a command off with its Enabled switch disables it on that server only: it stays visible in Discord but replies “This command is disabled on this server.”

The bot’s replies

Reply	Cause
“This Discord server isn’t linked to any SuperMDT organisation.”	the command was typed on a server that isn’t linked
“Your Discord account isn’t linked to any member of …”	the member never signed in to the MDT with this Discord account
“You don’t have permission to use this command.”	missing permission or module in their services
“None of your services matches.”	the service picked isn’t one of theirs on this server
“You’re assigned to several services: specify the service.”	/absence without service, for a member of several services
“You are suspended in this service.”	/absence during a suspension
“Absence declared.” or “Absence declared: it’s awaiting approval.”	the absence is created, approved straight away or pending
“Invalid dates…”, “An absence already covers some of these days.” or “Give a reason (1000 characters at most).”	/absence refused
“Something went wrong. Try again in a moment.”	a temporary error
“SuperMDT is unavailable right now. Try again in a moment.”	SuperMDT didn’t answer in time (the only bot message always in English)

The Accept button of a prosecutor or lawyer request also answers only the member who clicks: “Done: you are now assigned to file …”, “This request has already been taken or is no longer open.”, “You can’t accept this request…” or “Request not found.”

Sending log

The Log tab (on the home for every server, with a Server filter; inside a server for that server only) lists every message and sync the bot sent: Announcement, Absence, Sanction, Summons, Shift start, Shift end, Prosecutor or lawyer request, Roles and nickname, Server read, Leaving the server, Direct message, Test and Message deletion. An unlinked server shows as Unlinked server.

Status	Meaning
Pending / Sending	in the bot’s queue
Sent	done
Skipped	nothing to do: member not on the server, message already deleted, server unlinked
Failed	Discord refused; Discord’s error shows under the line

A temporary failure is retried automatically, 5 attempts at most (“3 attempts” shows next to the topic). The log loads 20 lines at a time, with Show more, and keeps 30 days of history.

Screenshot coming soonstart-discord-log

The bot’s sending log

What you set on Discord

SuperMDT can’t change your Discord server’s settings for you. Check these in Discord’s Server Settings:

1. The bot role’s position. In Roles, drag the SuperMDT role above every role it must give and above your members’ roles. A bot can neither give a role placed higher than its own, nor rename someone whose highest role is above its own.
2. The bot’s permissions. It needs: View channels, Send messages, Embed links, Read message history, Manage nicknames and Manage roles. They are requested on invite; if someone removes one, the Missing permissions badge appears and Re-invite the bot restores them.
3. Posting channels. If a channel is private, add the bot’s role to its permissions (view, send, embed links), otherwise it stays greyed out in the list.
4. Mentioned roles. For a Role to mention to actually notify, turn on Allow anyone to @mention this role on that role.
5. Command access (optional). In Integrations › SuperMDT, Discord lets you restrict each command to certain roles or channels, on top of the MDT’s permissions.

After moving roles, click Resync all members.

Direct messages

The bot also sends personal notifications by direct message to members who linked their Discord account and chose it, with an Open in the MDT button. Each member sets their categories in My profile › Notifications; the organization allows direct messages or not, and for which categories, in Settings › Notifications. Rate limits, grouped repeats and closed direct messages: see Notifications.

Limits

• 20 servers per organization; a Discord server is linked to one organization only; a service is covered by one server only.
• Roles and nicknames only apply to members who have signed in to the MDT with Discord.
• The Discord server owner can never be renamed.
• Direct messages only carry personal notifications: posts (announcements, absences, sanctions…) always go through channels.
• The bot doesn’t read your server’s messages; it only writes there and manages the mapped roles.

For the team hosting SuperMDT

There is a single bot for every organization, and it uses the same Discord application as sign-in (otherwise the warning “The running bot doesn’t use the same Discord application as sign-in” shows). In the Discord developer portal, the application must accept the redirect address <Convex site address>/discord/install. Receiving member joins requires turning on the privileged Server Members Intent in the portal’s Bot tab, then DISCORD_MEMBERS_INTENT=true for the bot. Until the application is configured, Add a server is greyed out and a warning explains why.