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
  • 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.

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