🎉 Discord Giveaway Bot

Multilingual, per-guild configurable giveaway bot built on discord.js v14, persisted via MariaDB (Prisma). Restart-safe poll scheduler, button entry, eligibility rules, weighted bonus entries, templates, pause/resume, edit & extend, "ending soon" reminders, winner DMs and reroll.

➕ Add to your server

Invite the bot →

This is the easiest way to use the bot — just invite the official instance. (You can also get this link any time via the /ginvite command.)

📚 Documentation

Full guide — getting started, the complete command reference and per-server configuration: docu.msk-scripts.de → Giveaway Bot

Requirements

• Node.js 22.x
• MariaDB (locally via Docker or a server)
• A Discord application with a bot token

Setup

npm install
cp .env.example .env

.env:

DISCORD_TOKEN=
CLIENT_ID=

# optional, for fast dev deploy
GUILD_ID=

DATABASE_URL="mysql://user:pass@localhost:3306/giveaway_bot"

MariaDB via Docker (local/test)

docker run -d --name giveaway-mariadb \
  -e MARIADB_ROOT_PASSWORD=root \
  -e MARIADB_DATABASE=giveaway_bot \
  -p 3306:3306 mariadb:11

Migrate the database

npm run prisma:generate
npm run prisma:migrate      # creates the tables (DB must be running)

Register slash commands

npm run deploy              # guild commands if GUILD_ID is set, otherwise global

Start the bot

npm start                   # or npm run dev (node --watch)

Static verification (no DB/token)

npx prisma validate
npm run prisma:generate
npm run smoke               # load smoke test (exports + builder constraints)
npm run i18n:check          # locale completeness en/de/fr/es

Commands

Command	Permissions	Description
/gcreate	Manager	Modal → giveaway in the current channel (incl. optional prize)
/gedit <id>	Manager	Edit a running giveaway (title, description, winners, prize)
/gextend <id> <duration>	Manager	Extend a running giveaway's end time
/gcancel <id>	Manager	Cancel an active giveaway
/gend <id>	Manager	End immediately + draw winners
/greroll <id> [winner]	Manager	New winners for an ended giveaway — or replace a single winner
/glist	everyone	List active giveaways
/ginfo <id>	everyone	Details about a giveaway
/gstats	everyone	This server's giveaway statistics
/ghelp	everyone	Command overview
/ginvite	everyone	Invite link
/gsettings show	ManageGuild	Show settings
/gsettings set …	ManageGuild	Set/add a setting: lang, color, emoji, button, blacklist, whitelist, bonus, minaccount, minmember, manager, notify, log, reminder, claim
/gsettings remove …	ManageGuild	Remove/clear a setting: blacklist, whitelist, bonus, manager, notify, claim
/gpause /gresume	Manager	Pause / resume a giveaway
/gtemplate save|list|delete|use	Manager	Giveaway templates

"Manager" = Manage Server OR the configured manager role.

set/remove blacklist, whitelist and bonus accept an optional giveaway_id to scope a role to a single giveaway (in addition to the server-wide values). See the documentation for the full command and configuration reference.

Permissions / Invite

/ginvite builds the invite URL from PermissionFlagsBits (not hardcoded): ViewChannel, SendMessages, EmbedLinks, ReadMessageHistory, UseExternalEmojis, MentionEveryone (integer 478208). allowedMentions restricts runtime pings specifically to the notify role.

Web dashboard & public results (msk-scripts.de)

The official instance integrates with msk-scripts.de:

• Web dashboard — …/giveaway/dashboard lets server admins (Discord login, Manage Server) create and fully manage giveaways and per-server settings from the browser. The shop proxies every action to a localhost-only HTTP control endpoint in the bot (services/controlServer.js, header X-Control-Secret = CONTROL_SECRET), so all Discord side-effects and the settings cache stay consistent. No public port is opened.
• Public results page — when a giveaway ends, the bot pushes the winners (username) and the anonymous participant count to the shop (RESULT_PUBLISH_URL, Authorization: Bearer ${RESULT_PUBLISH_SECRET}), which hosts a results page at …/giveaway/g/<token> and links it in the results message + winner DMs. The full participant list is never published.

Both features are optional and disabled until their env vars are set (CONTROL_SECRET, RESULT_PUBLISH_URL + RESULT_PUBLISH_SECRET). See .env.example.

Deployment (server)

Short version:

• On the server use npm ci (full install — the prisma CLI is a devDependency and is needed for generate/migrate), then npx prisma generate + npx prisma migrate deploy.
• Run via systemd (deploy/discord-giveaway.service), auto-restart, journald logs.
• Register commands globally: npm run deploy:global (registers global + removes guild commands).
• Only the Guilds gateway intent is needed — no privileged intents, no inbound port.

Self-Hosting

Running your own copy of this bot is neither supported nor encouraged. The code is published for transparency — so users can see exactly how the bot behaves and fellow bot developers can learn from the implementation — not as a ready-made product to redeploy.

In practice this means:

• There is no support for installing, modifying, building, or otherwise getting your own instance to run. Questions of that kind will not be answered.
• The setup and deployment notes in this repository exist for operating the official instance; use them at your own risk.
• Any modifications must be documented as required by the project license.