How Tos

Prerequisites

Before deploying the bot, make sure you have the following ready:

  • A Bot Token and Client ID from the Discord Developer Portal.
  • No Privileged Intents are required! The bot relies entirely on modern slash commands.
  • If running locally: Node.js (v16.14.0 or higher)
  • If running via containers: Docker and Docker Compose (Recommended)

Deployment & Setup Guide

Follow these steps to deploy and run Scotch Egg Bot. The setup below details the recommended containerized installation using Docker Compose.

🐋

Recommended Deployment: Docker Compose

Using Docker Compose is strongly recommended for hosting Scotch Egg Bot. It pre-configures Node.js, database folders, and permission environments inside an isolated container, making installation foolproof and keeping background process monitoring automated.

1. Download the Bot

First, download the bot's files and extract the ZIP file into a folder on your computer.

2. Discord Credentials & Environment Setup

Before configuring the bot, you need to grab a few credentials from Discord:

  1. Go to the Discord Developer Portal and click New Application.
  2. On the "General Information" page, copy your Application ID (this will be your CLIENT_ID).
  3. Navigate to the "Bot" tab on the left, click Reset Token, and copy the new password token (this will be your DISCORD_TOKEN).
  4. Go to "OAuth2" > "OAuth2 URL Generator". Check the bot and applications.commands scopes. Copy the generated URL at the bottom and open it in your browser to invite the bot to your server.

Now, create a new text file named .env inside your bot's folder and paste those credentials in like so:

DISCORD_TOKEN=your_actual_token_here
CLIENT_ID=your_bot_client_id_here
ADMIN_USER_ID=your_discord_user_id_here # Optional: Receives DM on errors
ANNOUNCEMENT_CHANNEL_ID=your_optional_fallback_channel_id_here

3. Initialize Database Files

Before starting Docker, create two new text files named events.json and config.json in your bot's folder. Add simply {} inside each file and save them. Or use the terminal:

echo "{}" > events.json
echo "{}" > config.json
⚠️ Windows / PowerShell Note: Using redirection (>) in some versions of PowerShell can create files with UTF-16 LE encoding, which will cause JSON parsing crashes on bot startup. If the bot throws a syntax error, simply recreate the files manually in a text editor (like Notepad or VS Code) containing just {} and save them with UTF-8 encoding.

4. Start the Bot

Make sure Docker is open and running on your computer. Then, open your terminal (Command Prompt, PowerShell, or Terminal), navigate to the bot's folder, and run:

docker compose up -d --build

You can now see the bot running smoothly inside Docker!

5. Register Slash Commands (Once)

After the bot is running, you must register its commands with Discord. You only need to do this once. Run the following command in your terminal:

docker exec -it scotch-egg node deploy-commands.js
Alternative: Local Node.js Installation (No Docker) Show instructions

If you prefer not to use Docker, you can run the bot directly on your host system using Node.js. Make sure you have installed Node.js (v16.14.0 or higher).

1. Install Dependencies

Navigate to the bot's root directory in your terminal and install the required npm packages:

npm install

2. Initialize Database Files

Create empty files named events.json and config.json containing just {} in the root directory (similar to step 3 in the main guide).

3. Register Slash Commands

Register the bot's commands with Discord by running:

node deploy-commands.js

4. Start the Bot

Start the bot process using node:

node index.js

Note: In a production environment, it is highly recommended to use a process manager like PM2 to ensure the bot automatically restarts if it crashes or the system reboots.

Using the Bot

1. Set the Announcement Channel

Administrators must tell the bot which text channel to use for event announcements. Type the following command in any channel:

/settings channel

2. Creating Events

Simply use Discord's native Create Event button at the top of your channel list. The moment you create an event, the bot will instantly post a rich-embed announcement in your configured channel.

3. Opting In (The "Remind Me!" Button)

Users who want to be notified can click the ⏰ Remind Me! button on the announcement. Depending on the server's configuration mode, the bot will either DM them or publicly @ ping them in the channel at the configured intervals.

Updating the Bot

If you ever edit the code or download an updated version of the bot, applying the changes is simple and won't delete your data.

  1. Run the following command to rebuild the container with the new code: 
    docker compose up -d --build
  2. If your update includes changes to slash commands, register them by running: 
    docker exec -it scotch-egg node deploy-commands.js

Commands

All Commands

Administrator Commands

  • /settings channel Sets or changes the server's announcement channel.
  • /settings mode Sets the reminder delivery mode: Public (channel posts + @ mentions), Private (DM-only alerts), or Hybrid (channel posts with zero mentions + private DMs).
  • /settings view Admin command that shows current bot configurations.
  • /settings calendar Toggles the "Add to Calendar" button on announcements.
  • /settings threads Toggles the automatic creation of discussion threads.
  • /settings autodelete Toggles whether event announcements are completely deleted when the event ends, rather than just being gracefully archived.
  • /settings intervals Sets custom reminder intervals using a comma-separated list.
  • /settings testreminder Displays a mock preview of what a reminder message will look like with the server's current settings.
  • /settings cleanup Scans the announcement channel's recent messages, automatically archives (or deletes) concluded event announcements, and performs a deep fail-safe scan (matching event links and event names) to delete all matching public event reminder messages to reduce channel clutter.
  • /announceevent Manually forces the bot to post an announcement for an existing event (useful if the bot was offline when the event was originally created).
  • /stats Admin command to view opt-in statistics for upcoming events in this server.

Public Commands

  • /upcoming Public command to view a paginated list of upcoming events and quickly opt in to reminders.
  • /myreminders Lists a paginated view of all upcoming events you are currently receiving reminders for.
  • /help Displays information on how to use the bot and a list of available commands (dynamically filtered to only show Administrator commands to server administrators).

Miscellaneous

Core Features

Scotch Egg is designed to be highly reliable, private, and fully automated. Below is a detailed overview of the bot's features, categorized by user-facing Discord capabilities and the robust technical architecture under the hood.

💬 Discord & User-Facing Features

✨

Native Discord Events

Just create an event using Discord's built-in scheduled event UI, and the bot handles the rest instantly. No need to learn any complicated commands to create events.

🔔

Strictly Opt-In Reminders

No mass @everyone spam. Members click a simple "Remind Me!" button to explicitly choose which events they want to be notified about via Private DMs, Public Mentions, or Hybrid Mode.

⚙️

Flexible Delivery Modes

Choose between three configuration options: Public channel reminders with pings, Private DM-only alerts, or Hybrid mode (un-pinged public reminders + private DMs).

⏱️

Custom Reminder Intervals

Admins can fully customize when reminders are sent (e.g., 24h, 1h, 15m before start) to suit the community using interactive slash command settings.

📅

Add to Calendar & View Buttons

Features interactive link buttons. The "Add to Calendar" button populates Google Calendar with event details, while "View Event" links directly to native Discord events.

💬

Automated Discussion Threads

Automatically creates dedicated discussion threads under server event announcements to encourage community interaction and keep chatter organized.

🧹

High-Contrast Archiving & Cleanups

Grays out concluded announcements, strikes through obsolete timestamps, and deletes all public pings. Admins can run /settings cleanup to sweep legacy messages.

🌍

Multi-Language Support (Localization)

Fully translated at both server announcements and client slash command levels across 5 languages: English, Spanish, German, French, and Portuguese.

⚡ Runtime & Technical Features

💾

SD-Card Friendly Architecture

Explicitly optimized for single-board computers like the Raspberry Pi. Implements a lightweight JSON storage schema with batched minified disk writes to prevent SD card wear.

🩹

Automatic Database Self-Healing

Resilient dual-layer mechanism maintaining atomic .bak copies of configurations. If damaged, a recursive Regex-based JSON salvage parser rebuilds database files automatically.

🔄

Offline Startup Sync & Garbage Collection

Syncs live events with Discord upon boot. Schedules reminders for any newly created events and safely archives announcements/deletes reminders of events that concluded while the bot was offline.

🚀

Real-Time Event Hook Synchronization

Dynamically reschedules, deletes, or recreates scheduled reminder jobs in response to real-time Discord scheduled event creations, start time updates, or cancellations.

Example Announcements & Reminders

See high-fidelity mockups of how the bot's dynamic event announcements and opt-in reminders render inside Discord, including the automated changes when an event concludes.

🟢 Active / Upcoming Event Formatting

Server Announcement (Rich Embed)

Posted in the configured #events channel the moment a Discord Scheduled Event is created. Displays duration, time range, and a clickable Host user pill without sending unwanted push pings.

New Event: Sunday Brunch at Eggcellent Café

🗓️ Time: Sunday, May 31, 2026 11:00 AM to 1:00 PM (in 5 days)

📍 Location: Eggcellent Café (123 Yolk Street)

It's been far too long since we've had eggs benedict, french toast, and bottomless mimosas together. Also, we need our yearly consumption of Scotch eggs as well!

*Click the button below to receive a DM reminder at: 24h, 1h before the event begins!*

👤 Host @Daniel
⏱️ Duration 2 hours
⏰Remind Me! 📅Add to Calendar 🔗View Event

Reminder Alerts (Public Ping, Private DM, & Hybrid Mode)

DMs are sent in plain text for high-priority mobile push notifications. Reminders can be sent via public channel pings (Public), private DMs (Private), or a mixture of both where public reminders have zero mentions while pings are delivered privately via DM (Hybrid).

Public Channel Reminder (Public Mode: with mentions | Hybrid Mode: identical, but zero mentions)

📢 1h until Sunday Brunch at Eggcellent Café!

🗓️ Sunday, May 31, 2026 11:00 AM (in 1 hour)

📍 Eggcellent Café

@Daniel

@Admin

⏰Remind Me! 📅Add to Calendar 🔗View Event

Private DM Reminder (Plain Text)

📢 1h until Sunday Brunch at Eggcellent Café!

🗓️ Sunday, May 31, 2026 11:00 AM (in 1 hour)

📍 Eggcellent Café

🔕Cancel Reminders 🔗View Event

🔴 Concluded / Concluded Event Archiving

Concluded Announcement (Archived Embed)

Automatically updated when the event completes. Strikes through the title and metadata using clean web styling, blockquotes descriptions, removes cover images, and replaces actions with a disabled Completed button.

New Event: Sunday Brunch at Eggcellent Café

⏹️ This event has concluded.

🗓️ Time: Sunday, May 31, 2026 11:00 AM to 1:00 PM

📍 Location: Eggcellent Café (123 Yolk Street)

It's been far too long since we've had eggs benedict, french toast, and bottomless mimosas together. Also, we need our yearly consumption of Scotch eggs as well!

✅Event Completed

How It Works (Storage Architecture)

To minimize disk wear on single-board computers (like the Raspberry Pi):

  • When an announcement is posted, it creates a record for that event in a local events.json file.
  • When a user clicks "Remind Me!", their Discord User ID is added to an object of opted-in users associated with that event's record. This object-based storage is highly efficient for lookups.
  • When it is time to send a reminder, the bot reads the opted-in users directly from the database and either DMs them or pings them publicly.
  • The database is automatically pruned when events are deleted, canceled, or completed to keep it lightweight.

Frequently Asked Questions

Does the bot support multiple servers (Guilds)?

Yes! You can invite the bot to as many servers as you want. Just use /settings channel in each server to configure where announcements should be posted.

What happens if the bot goes offline?

Every time the bot starts up, it performs "Offline Garbage Collection." It automatically syncs with Discord, schedules reminders for any new events it missed, deletes data for canceled events, and automatically archives or deletes announcements for events that concluded while it was offline. Additionally, administrators can run the /settings cleanup command at any time to scan the channel and clean up any legacy concluded events.

Why are the DM reminders plain text instead of Rich Embeds?

This is intentional. When an event URL is sent in a DM, Discord automatically generates a Rich Embed preview for it. If the bot sent an Embed, it would result in a cluttered "double-embed" in the user's DM.

What is the Hybrid delivery mode and when should I use it?

Hybrid mode is the best of both worlds! It posts all event reminders in your public announcement channel (providing a gorgeous, searchable, and clean chronological stream of events) but with zero pings or user mentions to avoid public chat disruption. Simultaneously, the bot delivers private, custom-localized direct messages directly to each opted-in member. Use this to keep channels tidy while guaranteeing that interested users never miss a notification.

Can users opt out of reminders?

Yes! Users can click the "Remind Me!" button again, click "Cancel Reminders" in a DM, or use the /myreminders command to opt out.

How does the Multi-Language support work?

Scotch Egg automatically detects the preferred language of your Discord server to translate public event announcements. It also dynamically detects each user's specific Discord client language to instantly translate interactive slash commands, options, select menus, confirmation replies, and DM reminder alerts on the fly! The bot is fully localized in English, Spanish, German, French, and Portuguese.

How does Database Self-Healing protect my data?

If your host device (like a Raspberry Pi) experiences a sudden power outage during a disk write, the active database file can get truncated or corrupted. On startup, Scotch Egg Bot automatically attempts to load the database, falling back to a `.bak` copy if the primary is damaged. If both are corrupted, it executes a Regex salvage parser to scan the damaged file, extract all intact records, and rebuild the database structure automatically.

Troubleshooting

Bot shows as online, but slash commands don't work / don't appear

You likely forgot to run the command registration script! Make sure your bot is running, then execute the command from Step 5 of the setup guide. You might need to restart your Discord client afterwards to see the commands.

The bot is not posting announcements or shows permission errors in the channel

The bot requires explicit role permissions in your configured announcement channel to operate. Make sure that the bot's integration role (or the bot itself) is granted the following permissions in the target channel's settings: View Channel, Send Messages, and Embed Links. If the bot is missing any of these, it will fail to post announcements or return descriptive permission warning responses.

Why aren't some users receiving their private DM reminders?

This is almost always due to Discord direct message privacy settings. If a user blocks DMs from server members, the bot is blocked from messaging them. To fix this, the user must go to their Server Privacy Settings in Discord and toggle "Allow direct messages from server members" to On. Alternatively, server admins can switch the server's mode to Public so reminders are posted directly in the channel with pings.

Docker created folders named "events.json" and "config.json"

If you don't manually create the events.json and config.json files on your computer before running docker compose up, Docker assumes you meant to map folders. Delete those folders, create the text files with {} inside, and restart the container.

I see "Interaction Failed" when clicking buttons

This usually means the bot is offline or has crashed. Check your Docker logs to see what happened. If you are not using Docker, check the terminal window where you started the bot.