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
- show each linked player's Discord profile picture next to their name on your website — read at login and during the role and nickname sync, never on page view
- assign or remove roles
- send direct messages
- create dedicated ticket channels, and a category plus a managed role per support level
- keep a private chat channel for every faction and every alliance, see Faction and alliance chats
- 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
- keep a leaderboard message up to date in a channel
- show live numbers — players online, kills today and more — as the names of locked voice channels, see Voice channel counters
- show every player their own profile and statistics with
/player - let players handle their balance, orders, places, bets, bounties, faction, base alarms and events with slash commands — see Discord commands
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. After adding the bot, Discord sends the admin back to the Discord step of the setup wizard with that Discord server selected.
Only the server owner or a member with the Administrator permission on the Discord server can connect it, and the Discord server list only offers Discord servers where the signed-in admin has that standing.
The install link asks Discord to give the bot Administrator, so it can use private channels without any setup. If you untick it, the bot only sees channels where its role is allowed in, and a private channel you pick for the online list, the leaderboard, the rules or an automation shows up in the Discord Integration Audit until you grant the bot role View Channel and Send Messages there. Adding the bot again resets its role to the permissions you confirm in that dialog, so anything you added to the role by hand is gone afterwards.
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.
Player roles
The bot creates and maintains three roles per game server the first time it needs them:
| Role | Who holds it |
|---|---|
| Online | players currently on the game server |
| Connected | players who linked their game account to Discord |
| Rules accepted | players who accepted the server's rules |
Each name ends with the server's subdomain, for example Online (myserver), so the roles of several game
servers sharing one Discord stay apart. Faction roles carry just the faction name unless you set a
faction role prefix. dzbot finds its roles by id, not by name — you can rename them freely.
Roles created before the subdomain was added are renamed once; a role you already renamed stays as it is.
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 the request type belongs to, wherever its panel is posted — see Multiple game servers in one Discord guild
Players do not need a panel at all: /ticket, visible to every member, offers the same request types —
one type opens its form directly, several show a private selection list first. Details in the
Tickets concept.
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.
Acting on a player from Discord
Moderators do not have to open the panel for routine work. Three entry points lead to the same card:
- right-click a member → Apps → Look up player
- right-click a message → Apps → Look up player — resolves the message's author
/player <username>— for players who never linked a Discord account and so cannot be right-clicked. If several players match the name, the bot offers a picker rather than guessing. Without a name,/playershows the moderator's own profile (see below).
The card is ephemeral: only the moderator who opened it sees it. It shows status (whitelisted, banned and until when, claim-blocked), balance, last seen, how many notes exist, and — depending on configuration — position, groups, factions and recent orders. A link opens the same player in the panel.
The buttons on it are the actions the moderator actually holds rights for; the rest are not drawn at all rather than shown disabled:
| Button | Right |
|---|---|
| Whitelist / Remove whitelist | admin.players.whitelist |
| Remove claim block — only while the player is blocked | admin.players.unblock |
| Notes | admin.players.view |
| Add note | admin.players.edit |
| Warn | admin.players.warn |
| Send DM — only if the player has a linked Discord account that accepts DMs | admin.players.send_discord_dm |
| Give money / Remove money | admin.players.change_money |
| Free item | admin.players.give_free_items |
| Orders | admin.orders.view |
| Ban | admin.restrictions.create |
| Unban | admin.restrictions.edit |
Opening the card at all needs admin.players.view on that server. Note, warn, money, ban, unban and DM open a small form. Unlike the browser, a ban from Discord always requires a reason; its Reason choice marks a ban for cheating, like Reason: cheating on the website. Unban asks why the ban is lifted and optionally takes a ticket code to link; used inside a ticket channel, that ticket is linked automatically.
- Remove claim block lifts the 24-hour block a player gets after guessing the wrong position while linking their account, so they can try again right away.
- Send DM writes to the player as the server's support staff: the bot puts a line naming the server above the text, exactly like the DM from the player page in the app. The text (up to 1,500 characters) is sent as soon as the form is submitted and is recorded in the audit trail.
- Free item puts one of the server's item sets into the player's cart for free, like Free cart item on the player page. Type part of the set's name or a class name (or nothing, to see all sets), pick the set from the list, then confirm. The player receives it with their next order. Hand-picked single items are only possible in the app.
- Orders lists the player's 20 latest orders — see
/orders. - Warn gives a warning: what it is for, when it expires (
30d,7d, … or empty for never), an optional Discord timeout (1 minute to 1 week) and whether the player is told by DM (yes by default). The answer says how many active warnings the player now has, whether the DM and the timeout went through, and whether a warning stage banned the player. The Notes field on the card shows the number of active warnings, and the notes list marks warnings and expired notes. A timeout needs the bot permission Moderate Members; when it is missing, the Discord audit page lists it.
/player for players: their own profile
/player is visible to everyone. Anyone without admin.players.view gets their own profile, never someone else's: a name they type is ignored and the card says so. It mirrors the web profile page — name, balance, playtime, last seen, factions, and the statistics groups combat, activity, building and casino, switched with buttons. It counts from the stats wipe date like the web page and shows nothing from the moderator card (no notes, position, whitelist or ban state, no action buttons).
A player whose Discord account is not linked to a player on that server is told to use /link with their in-game name first. The card needs the same right as the web profile (player.shop_profile.access), so banned players do not get it either. The two Look up player context-menu entries are listed for everyone too and work the same way: without admin.players.view they open the caller's own profile.
The context-menu entries and slash commands are global Discord commands. Every deployment registers them again automatically, so a new or changed command shows up without any action from you — Discord may take a few minutes, or a client reload, to show it.
Voice channel counters
dzbot can show live numbers of your server as the names of voice channels, for example 🟢 Online: 34/60 or ⚔️ Kills today: 112. Turn them on under Server Admin → Settings → Discord → Voice channel counters.
| Counter | Shows |
|---|---|
| Online / slots | players online now, and the server's slots |
| Kills today | PvP kills since midnight — the kills that count for the leaderboards (no excluded kills, no spawn kills) |
| Deaths today | every player death since midnight |
| Longest kill today | the longest of today's kills, in meters |
| Best kill streak today | the most kills anyone made today without being killed |
| Open bounties | how many bounties are open right now |
| Most players at once today | the highest number of players online together today |
| Players today | how many different players were on the server today |
"Today" starts at midnight in your server's time zone (Settings → Server → Time zone).
How it behaves:
- dzbot creates the channels. The first counter you switch on makes dzbot create a category,
📊 Server stats, with one voice channel per counter. The channels are visible like your other channels, but nobody can join them. - Names change at most every six minutes. Discord allows two renames per channel in ten minutes, so dzbot checks every six minutes and only renames a channel whose number changed. A number can lag behind by that much.
- The name is yours. Each counter has a name with
{value}where the number goes. Leave it empty for the default in your server's language. - Switching a counter off deletes its channel. With every counter off, dzbot also deletes its category, unless you put other channels into it.
- Deleting a channel by hand does not stick. As long as its counter is on, dzbot creates it again on its next run — switch the counter off instead.
- You can move and rearrange the channels. dzbot leaves moved channels where they are and only renames them. It creates a new category only when it has to create a channel and its own category is gone.
- Several game servers on one Discord each get their own category, named after the server —
📊 <server name>. The counters never need to be claimed under Owned Discord Categories, because nobody can interact with them.
The bot needs Manage Channels and Manage Roles, and the Connect permission it takes away from everyone else on these channels. If it is missing any of them, the counters stay as they are and the Discord audit page says what to grant.
Channel names and what they give away
By default a ticket channel is named after the ticket's subject and a base-alarm channel after the faction or player it belongs to. Everyone who can see the channel list can therefore read those names.
The setting Anonymize Discord channel names replaces them with the entry's code: ticket-7kqm and base-alarm-7kqm. Switching the setting off and on again renames existing channels. It covers ticket channels and base-alarm channels; no other channel kind is affected.
Two details matter:
- New servers have it on. Existing servers were explicitly left as they were when the setting was introduced, so they keep the revealing names until someone turns it on.
- Toggling renames the channels that already exist, in both directions. Turning it on is not only a rule for the future.
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