Skip to main content

Discord integration concept

This page explains how Discord integration works in dzbot and what to check when Discord features are missing.

What Discord integration enables​

Depending on your configuration and permissions, dzbot can:

  • link players to Discord accounts
  • sync nicknames with in-game names
  • assign or remove roles
  • send direct messages
  • create dedicated ticket channels, and a category plus a managed role per support level
  • post request-type panels players open tickets from, and show them the intake form as a Discord dialog
  • post to support or alarm channels
  • maintain an online players list channel

Bot installation basics​

The bot install prompt is shown as an admin alert when both of these are true:

  • a Discord Server from the admin's connected Discord account is selected in settings, and
  • dzbot detects that the bot is not installed on that server.

The alert includes a Discord OAuth link to add the bot and a recheck link once it is installed. It does not appear for players or on the shop frontend.

To run the full setup flow, follow Getting started: Connect Discord integration.

Sharing one guild between multiple game servers​

Several dzbot servers can select the same Discord Server, so a community can run two game servers on one Discord. Inbound events (AI companion mentions, tickets opened from Discord) are then routed by the channel's category via the Owned Discord Categories setting. This needs deliberate configuration — see Multiple game servers in one Discord guild for the setup guide and pitfalls.

Ticket support levels​

Each support level of a server owns two Discord objects, both created and maintained by the bot:

  • a category the level's ticket channels live in, so staff working one level only have to look at one place. It is created when the level is created and can be swapped later from Server Admin -> Tickets -> Levels; swapping it moves the level's existing channels along.
  • a role whose membership follows the level right in dzbot. dzbot rights are the single source of truth here, exactly as for the connected and online roles — do not assign it by hand.

Because level visibility is cumulative, a staff member holding level 3 also receives the roles of levels 1 and 2, keeping the lower categories readable.

Escalating a ticket moves its channel into the target level's category and swaps the role overwrites. The level stored in dzbot is authoritative: if a Discord call fails the app still hides the ticket correctly and only the channel sits in the wrong place, which Re-sync Discord on the ticket repairs.

The former server-wide "Discord Tickets Support Role" setting has been removed — a single role that reads every ticket channel is a back door in a level-separated system.

Ticket request-type panels​

A request type can own a panel in as many Discord channels as you need — one per channel: an embed with the type's name and description and one "open ticket" button per maintained language. Pressing a button opens that type's intake form as a Discord dialog, and the ticket is created from the answers — the player never leaves Discord. Every panel of a type is interchangeable, so a ticket opened from a guest channel is the same ticket as one opened from a members channel.

What this means for your Discord setup:

  • the bot needs permission to post in each panel channel; without it, publishing there fails with a warning and nothing else breaks, because ticket creation does not depend on panels. A save that cannot reach one channel still updates the type's other panels
  • every panel is edited in place whenever the type changes, so the buttons always match the current form. If someone deletes a panel message, the next save notices and offers to publish it again
  • Discord cannot move a message, so reordering the request types does not reorder the panels — the Rebuild panels action in the editor reposts the panels of one channel
  • a Discord dialog takes at most five inputs and cannot be followed by a second one, which is why an intake form is capped at five fields on both surfaces
  • on a shared guild the ticket is created on the server that owns the panel channel's category, so panels belong inside their server's owned categories — see Multiple game servers in one Discord guild

Panels are published and rebuilt from Server Admin → Tickets → Categories; the mechanics behind the form itself live in the Tickets concept.

Role hierarchy requirements​

Discord only lets a bot manage roles that are below the bot's role. If role sync does nothing, move the bot role above the roles it must manage. To ensure that the bot can do everything it needs to, make sure it has the highest role in the system.

References: https://docs.discord.com/developers/topics/permissions https://support.discord.com/hc/en-us/articles/214836687-Discord-Roles-and-Permissions

Nickname permissions​

To update its own nickname, a bot needs Change Nickname. To update other members' nicknames, it needs Manage Nicknames.

References: https://support.discord.com/hc/en-us/articles/219070107-Server-Nicknames https://docs.discord.com/developers/topics/permissions

Opt-in and opt-out behavior​

If a user opts out, Discord-based notifications stop for that account. There is two ways players can opt out of Discord messages:

Automatic opt-out on bot block​

When the player blocks the bot in discord, the player is automatically opted out.

Explicit opt-out​

we provide an explicit opt-out endpoint that are linked in all messages the bot sends to players directly (via DMs, not in channels). This allows players to easily stop receiving Discord notifications if they wish.

Troubleshooting opt-outs​

Many times out-outs are done without realising the consequences (or unknowningly using bot blocking). If players complain about not receiving notifications (like base alarms), always check the opt-out status of the player in question by using the impersonation feature. Opt-out players get a big warning on all pages in the shop to re-out-in.

Common checks when Discord features fail​

  • Discord Server is selected in Server Admin → Settings from the admin's connected Discord account
  • the channel/category dropdowns were refreshed after changing the selected Discord server
  • bot is installed on the correct guild
  • bot role is above roles it manages
  • required permissions are granted
  • player is opted out