BSG Nexus โ€” Admin Documentation

Table of Contents

  1. Initial Setup
  2. Web Panel
  3. Settings Reference
  4. Message Templates
  5. Ticket System
  6. Bot Language & Timezone
  7. Multi-Server Operation
  8. Event Pipeline
  9. Data & Privacy
  10. Troubleshooting

1. Initial Setup

Step 1 โ€” Invite the Bot

Use the invite link from your service provider. Required permissions: View Channels, Send Messages, Manage Messages, Manage Channels (for tickets), Embed Links, Attach Files, Read Message History, Add Reactions.

Enable in Discord Developer Portal โ†’ Bot โ†’ Privileged Gateway Intents: Server Members Intent, Message Content Intent.

Step 2 โ€” Run /setup

/setup
  admin_rolle:        Admin
  kontroll_kanal:     nexus-control
  spiele_kanal:       nexus-spielesammlung
  ankuendigungs_kanal: bekanntmachungen
  willkommens_kanal:  eingangshalle
  poll_kanal_id:      (right-click #polls โ†’ Copy ID)
  stammtisch_kanal_id: (right-click #bekanntmachungen โ†’ Copy ID)
  spielname_kanal_id: (right-click #gewinner-spiel โ†’ Copy ID)
  event_name:         Game Night
  bot_sprache:        en
  zeitzone:           Europe/Berlin

Step 3 โ€” Post Game Board

/gameboard

Step 4 โ€” Schedule First Event

/events eingabe: 31.12.25 20:00

2. Web Panel

Login via Discord OAuth at the URL provided by your service provider.

Page Function
Dashboard Overview, system load, activity graph
Games View, rename, delete games
Appointments View appointments and pipeline status
Warnings Manage user warnings
Notes Admin notes
Announcements Scheduled announcements
Tickets Ticket list, transcripts, force-close (Pro)
Settings All configuration
Bot Status System gauges, task status (owner only)
Activity Log Audit trail of web panel actions

Language & Timezone


3. Settings Reference

Bot & Channels

Field Description
Admin Role Role(s) for bot commands. Multiple: Admin, Moderator
Bot Language Discord messages: English or Deutsch
Timezone For event input parsing (default: Europe/Berlin)
Event Name Used in all automated messages

Channel IDs (right-click channel โ†’ Copy ID)

Field Used For
Poll Channel ID Game selection polls
Event Channel ID Announcements, reminders, cancellations
Game Name Channel ID Winning game name only
Warning Threshold DM Recipient Discord User ID for threshold DMs

Games & Events

Message Templates

Fully customizable. See Message Templates.

Auto-Moderation (Pro)

Automatic action when warning threshold is reached. See Settings โ†’ Auto-Moderation.

Ticket System (Pro)

See Ticket System.


4. Message Templates

All automated bot messages support placeholders.

Placeholders

Placeholder Value
{event_name} Configured event name
{weekday} Day of week in bot language
{time} HH:MM
{date} DD.MM.YYYY HH:MM
{game} Winning game name
{hours} Reminder hours
{server} Server name
{member} Member mention
<t:{timestamp}:F> Discord auto-timezone timestamp (recommended)
<t:{timestamp}:R> Relative time (e.g. "in 2 hours")

Default Templates

Announcement: ๐Ÿ“ข **{event_name}** <t:{timestamp}:F>: The game is **{game}**!
Reminder: โฐ **Reminder:** {event_name} <t:{timestamp}:R> โ€” in {hours} hour(s)!
Cancellation: ๐Ÿ“ข The **{event_name}** scheduled for <t:{timestamp}:F> has been cancelled.
Welcome: ๐Ÿ‘‹ Welcome to **{server}**, {member}!
Poll Title: ๐ŸŽฎ {event_name} ยท {date} (timestamps not supported in polls)


5. Ticket System

Available in the Pro plan.

Setup

  1. Configure in Settings โ†’ Ticket System:
  2. Enable the ticket system
  3. Set the Discord channel category ID (where ticket channels are created)
  4. Set the log channel ID (where transcripts are sent on close)
  5. Set staff role(s)
  6. Configure topics (comma-separated, e.g. Support,Purchase,Bug Report)
  7. Customize the welcome message

  8. Run /ticketsetup #your-support-channel โ€” posts the panel embed with the Open Ticket button.

User Flow

  1. User clicks Open Ticket button
  2. Modal appears: choose topic, enter subject
  3. Bot creates private channel ticket-0001 โ€” visible only to the user, staff roles, and the bot
  4. Welcome message posted with Close and Claim buttons

Staff Flow

Web Panel

Welcome Message Placeholders

{user}, {topic}, {subject}, {number}, {server}


6. Bot Language & Timezone

Bot Language

Controls all Discord-facing messages: game board, announcements, command responses. - Set via /setup bot_sprache: en/de or Settings โ†’ Bot Language - Default: English

Guild Timezone

Used when parsing event times entered via /events or the web panel. - Set via /setup zeitzone: Europe/Berlin or Settings โ†’ Timezone - Default: Europe/Berlin - Full list: America/New_York, Asia/Tokyo, Australia/Sydney, etc.

Discord Timestamps

All bot messages use <t:UNIX:F> format. Discord automatically converts these to each user's local timezone โ€” no configuration needed for readers.

Web Panel Timezone

Each admin can set their own display timezone (auto-detected from browser). Click ๐Ÿ• in the sidebar to change. Affects how times are shown in the web panel โ€” independent from the guild timezone.


7. Multi-Server Operation


8. Event Pipeline

/events scheduled
       โ”‚
       โ–ผ
  T โˆ’ poll_before    โ†’ Game selection poll posted (default 1d 12h 30m)
                          Optional "Yes, but different game" button
       โ”‚
       โ–ผ
  T โˆ’ reminder_before โ†’ Reminder message (if reminder enabled, default 2h)
       โ”‚
       โ–ผ
  T โˆ’ winner_before  โ†’ Poll closed, winner announced with Discord timestamp
                        Game name sent to game name channel
                        Alt-game suggestions listed (if enabled)
       โ”‚
       โ–ผ
  T + delete_after   โ†’ Appointment deleted, vote counter updated (default 3h)

All four timings (poll start, winner/poll end, reminder, auto-delete) are fully configurable per guild via the web panel (Days / Hours / Minutes fields) or the /pipelineconfig command. The Discord poll duration is derived automatically as poll_before โˆ’ winner_before.

Tie handling: random selection among tied options, message notes the tie.


9. Data & Privacy

Data Purpose Retention
Guild config Bot operation 30 days after bot removal
Game names & votes Game board Until deleted
User IDs (cooldowns) Abuse prevention Until reset
User IDs (warnings) Moderation Until cleared
Ticket records Support history Until deleted by admin
Ticket transcripts Audit trail Until deleted by admin
Activity log Web panel audit Last 500 entries
Deleted messages Moderation log (Pro) Last 500 entries / 7 days per guild
Ban appeals Appeal tickets (Pro) Until deleted by admin
XP / levels Leveling (Pro) Until manually reset

See PRIVACY_POLICY.md / DATENSCHUTZ.md for full details.


10. Troubleshooting

Bot doesn't respond to commands
โ†’ Check admin role is correct. Slash commands may take up to 1 hour to sync after first setup.

Game board button doesn't work after restart
โ†’ Fixed automatically โ€” persistent views are re-registered on every bot restart.

Ticket channels not being created
โ†’ Bot needs Manage Channels permission. Check that the ticket category ID is correct.

Ticket transcripts not appearing in log channel
โ†’ Verify the log channel ID in Settings. Bot must have Send Messages + Attach Files permission there.

Discord timestamps show as plain text in polls
โ†’ Known Discord limitation โ€” timestamps don't render in poll questions. Use {date} instead.

Times in web panel are wrong
โ†’ Click ๐Ÿ• in the sidebar and set your timezone manually.

Polls don't appear
โ†’ Verify Poll Channel ID in Settings. Bot must have permission to send polls there.