Documentation

Complete reference for BetterGhast v3.0. Everything you need to set up, configure, and use the bot on your Discord server.

About BetterGhast

BetterGhast is an all-in-one Discord server management bot. It started as a tag management tool and has grown into a full-featured bot covering moderation, community engagement, and automation.

Core areas:

• Tag System — Reusable message snippets with templates, permissions, and analytics
• Moderation — Warning system with auto-escalation, auto-response triggers, anti-spam protection
• Community — Welcome messages, reaction roles, ticket system, leveling with XP, polls

BetterGhast is built with Kotlin, JDA 6, and MariaDB. It runs as a Docker container on any Linux server.

Setup & Installation

Quick Deploy (Docker)

git clone https://github.com/Krogie/BetterGhast.git
cd BetterGhast
bash deploy.sh

The deploy script handles everything: Docker installation, database setup, and bot configuration. It will ask you for your Discord bot token.

Discord Developer Portal

1. Go to discord.com/developers/applications
2. Create an application or select your existing one
3. Under Bot, enable Message Content Intent and Server Members Intent
4. Under OAuth2 > URL Generator, select scopes bot + applications.commands
5. Select the required permissions (see below) and invite the bot

Required Permissions

Tags — Overview

Tags are reusable message snippets that can be triggered by anyone in your server. They support full Discord markdown, media URLs, templates with placeholders, and role-based access control.

Tag Styles

• Accent Embed — Wrapped in a container with your custom accent color. Supports headers (lines starting with ###) and media galleries.
• No Accent — Same container formatting but without the colored accent bar.
• Raw Message — Sent as a plain text message with no embed. Useful for simple text responses.

Create & Edit Tags

The modal lets you set:

• Keywords — Comma-separated list of trigger words. The first one is the primary keyword. Example: nolfg, m, lfg
• Content — The tag message. Supports full Discord markdown, headers (###), and trailing media URLs.
• Style — Choose Accent, No Accent, or Raw.

Media URLs

If your tag content ends with a URL separated by a blank line, it will be displayed as an embedded media gallery (images, GIFs, videos).

### Welcome to our server!
Please read the rules in #rules before chatting.

https://example.com/welcome-banner.png

Templates & Placeholders

Tags support dynamic placeholders that are replaced when the tag is triggered:

Role Permissions

When a tag has a role restriction, only members with that role can trigger it via !t. Members without the role will get no response (silent fail). To remove a restriction, set the role to @everyone.

Tag Analytics

Shows:

• Top Users — Who uses tags the most (top 10)
• Usage Trends — Daily usage for the last 7 days
• Unused Tags — Tags that have never been triggered (cleanup suggestions)

Search, Stats & Export

Warning System Moderator

A full warning system with automatic escalation. Moderators can warn users, and the bot automatically takes action when thresholds are reached.

Escalation Thresholds

Default thresholds (configurable via WARN_THRESHOLDS in .env):

Warning Decay

Warnings automatically expire after a configurable number of days (default: 30). Expired warnings are marked as inactive and no longer count toward escalation thresholds. A background job checks for expired warnings daily.

Auto-Responses Admin

Automatically reply with a tag when a message matches a keyword or regex pattern. Useful for FAQ automation.

Regex Mode

Set regex:true when adding a trigger to use regular expressions. Example: pattern:(?i)how\s+(do|can)\s+i\s+join matches "How do I join", "how can i join", etc.

Per-Trigger Cooldown

Each trigger has a 30-second cooldown by default to prevent spam. The cooldown is per-guild per-trigger.

Anti-Spam Admin

Protects your server from spam, duplicate messages, suspicious links, and Discord invite links.

What Gets Detected

• Rate Limiting — Too many messages in a short time window. Configurable threshold and window.
• Duplicate Detection — Repeated identical messages (based on content hash).
• Link Filter — Messages containing URLs not on the whitelist.
• Invite Filter — Messages containing Discord server invite links.

Spam messages are automatically deleted. Optionally, the user receives an automatic warning via the warning system.

Users with the "Manage Messages" permission are exempt from anti-spam checks.

Welcome Messages Admin

Greet new members and say goodbye to leaving ones. Supports placeholders, auto-role, and optional DMs.

All placeholders from the Tags Templates section work in welcome messages too.

Reaction Roles Admin

Let members assign themselves roles by clicking buttons or selecting from dropdowns.

Button vs Dropdown

• Buttons (default) — Each role gets its own button. Click to toggle. Supports up to 25 roles (5 rows of 5).
• Dropdown — All roles in a single select menu. Members can select multiple roles at once.

How It Works

When a member clicks a button or selects a role from the dropdown, the bot toggles the role: adds it if the member doesn't have it, removes it if they do. No additional permissions needed from the member.

Ticket System Public

A support ticket system where members can create private channels for help requests.

How Tickets Work

1. An admin runs /ticket setup to configure the support role and post a ticket panel.
2. Members click "Create Ticket" or use /ticket create to open a ticket.
3. A private channel is created visible only to the member and the support team.
4. Support staff can /ticket claim the ticket to indicate they are handling it.
5. When resolved, anyone can /ticket close. A transcript can be generated before closing.

Leveling & XP Public

Members earn XP by chatting. As they level up, they can unlock special roles.

User Commands

Admin Commands Admin

How XP Works

• Members earn 15-25 XP per message (randomized)
• XP cooldown: 60 seconds between gains (prevents spam grinding)
• Level formula: level = floor(0.1 * sqrt(xp))
• Level roles are automatically assigned when a member levels up
• Channel multipliers let you boost or reduce XP in specific channels

Polls Public

Create polls with buttons for voting. Supports time limits, anonymous voting, and multi-choice.

How Polls Work

• Each option gets a vote button. Members click to vote (click again to unvote).
• Vote counts are updated live on the message.
• Polls can be closed manually by the creator or any admin, or automatically after the duration expires.
• Final results are posted when the poll closes.

Configuration

All configuration is done via the .env file. Here is a complete reference:

All Commands

Tags

Moderation

Community