Skip to main content

Discord

Account linking, chat relay, console channel, bug reports and webhooks between your server and Discord.

Freev0.13Integrations
RequiresTypeWriter0.9Basic extensionPaper1.21.6+optionalShopsoptional
DownloadSource codeSupport

Overview​

Discord connects your Minecraft server to your Discord server. Everything that goes to Discord uses one reusable object: a webhook destination (the URL of a Discord channel, plus a name and an avatar), declared once and referenced by every feature. To change the channel, you edit one entry.

The extension covers six jobs: account linking with rank-to-role sync, two-way chat relay, a console channel to run server commands from Discord, an in-game bug report system, shop transaction announcements, and webhooks published when a TypeWriter fact changes. Each feature is its own entry, so you only configure what you use. Discord is optional for the rest of TypeWriter: without a link manifest, no Discord bot is started.

This extension was named Community until version 0.9. Entry names did not change, and pages written before the rename are converted on first start.

Features​

  • Webhook destinations — one entry per Discord channel (URL, username, avatar, permanent role pings), shared by all features.
  • Account link — players run a command to get a code, type it in a Discord channel, and their accounts are linked; Discord roles follow their Minecraft groups.
  • Chat sync — Minecraft chat and join/leave messages go to Discord, and Discord messages can come back into the game.
  • Console channel — staff run server commands from a Discord channel, with a command list, role restriction and a log file.
  • Bug reports — an in-game dialog form, stored with status tracking, posted to Discord as an embed or a forum thread, and manageable from Discord slash commands.
  • Shop announcements — purchases and sales posted to the channel each shop names (requires the Shops extension).
  • Fact webhooks — a message when a TypeWriter fact changes, per player, per group or globally.
  • Automatic migration — pre-0.9 pages with inline webhooks are converted to webhook destinations.

Installation​

  1. Create a Discord webhook in the channel you want: in Discord, Channel settings, Integrations, Webhooks, New Webhook, then copy its URL. This is enough for webhooks, bug reports and one-way chat.
  2. For account linking, the Discord-to-Minecraft chat relay, the console channel and slash commands, you also need a Discord bot. Create it in the Discord Developer Portal, copy its token, invite it to your server, and enable the Server Members Intent and Message Content Intent under Bot. The extension requests these intents and cannot connect without them.
  3. Make sure the Basic extension of TypeWriter is installed (see the TypeWriter documentation).
  4. Put the Discord JAR in plugins/Typewriter/extensions/ and restart the server. The JAR already contains the JDA library used for the bot.
  5. For shop announcements, also install the Shops extension.

Bug reports use Paper's dialog screens, which need Paper 1.21.6 or later.

Getting started​

Link accounts and post bug reports to your staff channel:

  1. In the TypeWriter web panel, open a manifest page and add a Webhook Definition. Paste the channel URL in url, and optionally a username and avatarUrl.
  2. Add a Discord Link Storage artifact on the same page: it stores links and pending codes.
  3. Add a Discord Link Manifest. Set storage to the artifact, webhook to your destination, enable bot, and fill botToken and guildId. Set verificationChannelId to the Discord channel where players will type their code.
  4. Optional: fill roleMappings to give Discord roles by Minecraft group, for example minecraftGroup vip and the Discord role ID in discordRoleId.
  5. Add a Bug Report Sequence Storage artifact, then a Bug Report Manifest. Set commandName (for example bugreport), sequenceStorage, serverName, and at least one entry in categories, with an input whose key is description. In webhook, set destination to your destination.
  6. Publish. A player runs /discordlink to get a code, types it in the verification channel, and is linked. A player runs /bugreport to open the form.

To get a Discord channel or role ID, turn on Developer Mode in Discord's advanced settings, then right-click the channel or role and choose Copy ID.

How it works​

Sending uses a webhook, with no bot. Receiving from Discord needs the bot, which is configured only in the Discord Link Manifest. Without an enabled bot, the Discord-to-Minecraft chat relay, the console channel and the bug report slash commands do nothing.

An empty or disabled destination is the normal way of sending nothing. A reference to a destination that no longer exists is logged as Destination '…' not found; message dropped.

Configuration​

The extension is configured in the web panel. Link data and bug reports are stored in the artifact entries you create. Besides these, it writes:

FileContent
logs/discord-console.logCommands run from the console channel (relative to the server root; the path is a field of the entry).
backup/community-webhook-v1/Backup of the pages rewritten by the migration from Community, in the Typewriter folder.

Migration from Community​

Pages written before 0.9 stored the webhook inside each manifest. On the first start, the extension creates one Webhook Definition per distinct destination, points the manifests at it, and backs up every rewritten page first. It then asks you to run /typewriter reload once.

Commands​

The commands below are registered by the manifest entries. Their names are fields of those entries; the defaults are shown.

CommandDescription
/discordlinkGenerate a verification code, or repeat the pending one. Players only.
/discordlink unlinkRemove the link and the mapped Discord roles.
/bugreportOpen the category selection, then the report form.
/bugreport mineList your own reports.
/bugreport list [player]List reports, optionally of one player. Needs the admin permission.
/bugreport status <reportId> <statusId>Change the status of a report. Needs the admin permission.
/bugreport delete <reportId>Delete a report. Needs the admin permission.

With discordCommands on, the bug report manifest also registers a slash command in your Discord server, named like commandName, with list, status and delete. Only Discord administrators, or members with a role in discordAdminRoleIds, can use it.

Registering these slash commands replaces the other slash commands that this bot has in the server.

Permissions​

All permissions are fields of the entries and can be changed. Defaults:

PermissionGrants
discordlink.notifyReceive a message when a player links an account (notifyPermission; empty disables it).
bugreport.notifyReceive a message when a report is submitted (notifyPermission).
bugreport.adminUse /bugreport list, status and delete (adminPermission).
group.<group>Matches a role mapping: the first mapping whose group passes is the player's Discord role (groupPermissionFormat).

Entries​

9 entries, generated from the extension source.

Events1
Commands2
Artifacts2
Manifests4

Troubleshooting​

The bot does not connect. The console shows Failed to connect Discord Bot or Discord Bot is disabled or token is missing. Check that bot is enabled with the right botToken and that the Server Members and Message Content intents are on in the Developer Portal. The guildId must be the ID of the server: if it is wrong, you see guild not found.

/discordlink says linking is not configured. There is no Discord Link Manifest on a published page. The console shows discord_link_manifest not found; Discord link is disabled.

The code typed on Discord is ignored. Players must type only the code, exactly codeLength letters or digits, in the channel set in verificationChannelId. The bot reacts with a check or a cross. A code that expired (codeValidityMinutes), or a Discord account that is already linked, is refused. A player already linked is refused too, unless autoOverwriteExistingLink is on.

The bug report command says there are no categories. categories is empty by default. Add at least one category. A report is only accepted when its title or description input is filled, and the form adds the title input itself, so add an input with the key description for the message.

Bug reports are rejected by Discord. threadNameTemplate is meant for forum channels. If your destination is a normal text channel, empty the template. The console shows Webhook '…' rejected with HTTP … with the reason.

Console commands do nothing. The console channel needs the bot, and the channel ID in discordChannelId must match. A blocked command gets a no-entry reaction and an unauthorised member a cross. By default, commandList is a blacklist containing stop, restart and reload; switch to blacklistIsWhitelist and restrict allowedRoles for a safer setup.

Shop sales are not announced. You need a Shop Notification Manifest (without it, nothing is sent), and the shop definition must name the destination in its notificationWebhookId, using the ID of your Webhook Definition entry. The Shops extension must be installed.

  • Shops — its shops name the Webhook Definition that announces their transactions.