Welcome

Handles welcome and leave messages, CAPTCHA verification, raid protection, boost announcements, and sticky roles.

---

Modes: Banner · Embed · Text

Join supports embed and banner, Leave additionally supports text:

Mode	Description
banner	Canvas-rendered image, custom colors, optional background (cover-fit, any aspect ratio)
embed	Fully configurable Discord embed (title, description, color, thumbnail, footer, timestamp)
text (leave only)	Random text message from a list

Target channel comes from channels.welcome in configs/config.yml (NOT from the module YAML) — the same channel is used for join, leave, and boost.

In configs/modules/welcome.yml:

join:
  enabled: true
  mode: banner                # embed | banner
  contentMessage: "%user_mention% Welcome to **%guild_name%**!"
  embed:
    title: "Welcome to %guild_name%!"
    description: "Hey %user_mention%, glad you made it.\nYou are member **#%guild_members%**."
    color: "#57F287"
    thumbnail: "%user_avatar%"
    footer:
      text: "Joined %now_relative%"
    timestamp: true
  banner:
    backgroundColor: "#1a1a2e"
    accentColor: "#ff6b35"
    textColor: "#ffffff"
    backgroundUrl: ""         # custom background image (https://...), empty = gradient
    label: "· WELCOME ·"

leave:
  enabled: true
  mode: banner                # text | embed | banner
  messages:
    - "👋 **%user_name%** has left the server."
    - "👋 **%user_name%** is gone."
  embed:
    title: "Goodbye 👋"
    description: "**%user_name%** has left the server."
    color: "#ED4245"
  banner:
    backgroundColor: "#2a1a1a"
    accentColor: "#ed4245"
    textColor: "#ffffff"
    label: "· GOODBYE ·"
    subText: "Goodbye!"

Placeholders (%user_mention%, %guild_name%, %user_avatar%, %guild_members% etc.) are replaced in text, embed, and banner fields.

---

Verification

Flow:

1. A new member joins → gets roles.unverified (from configs/config.yml)
2. A persistent panel with a button hangs in the channels.verify channel, automatically re-posted on bot startup if the stored message is missing
3. The user clicks the button
4. The bot sends a CAPTCHA via DM — default is an image CAPTCHA, alternatively math (a text math problem)
5. Answered correctly → unverified role removed, roles.member role added

If DMs are closed: the bot shows instructions on how to enable DMs for the server.

Failed attempts/timeout: maxAttempts (default 3), timeoutSeconds (default 300). What happens afterward is controlled by failAction: kick (default), ban, or nothing.

verification:
  enabled: true
  logChannelId: "0"           # optional, log verify events separately
  captcha:
    type: image                # image | math
    timeoutSeconds: 300
    maxAttempts: 3
    sessionCooldownSeconds: 60
  panel:
    embed:
      title: "✅ Verification"
      description: "Welcome! Click below to verify."
      color: "#5865F2"
    buttonLabel: "Accept Rules & Verify"
    buttonStyle: "Primary"
    buttonEmoji: "📜"
  failAction: kick

---

Fake/Alt Account Protection & Raid Protection

Blocks the start of verification even before the CAPTCHA:

verification:
  protection:
    minAccountAgeDays: 7           # 0 = disabled
    requireAvatar: false           # true = reject accounts without a custom avatar
    blockedUsernamePatterns: []    # regex patterns for blocked names
    raid:
      enabled: true
      joinThreshold: 5             # at X joins ...
      windowSeconds: 30            # ... within Y seconds ...
      lockdownSeconds: 600         # ... triggers Z seconds of lockdown
      onJoinDuringLockdown: nothing  # nothing | kick | ban

End a lockdown manually: /welcome clear-lockdown.

---

Boost Announcements

When a member starts boosting the server, the bot posts a one-off thank-you message in the welcome channel. This is different from the pure boost counter in the Serverstats module (which just shows "currently X boosts" as a channel name) — this is the actual message posted at the moment of the event.

boost:
  enabled: true
  embed:
    title: "💜 New Boost!"
    description: "%user_mention% boosted **%guild_name%**! Thanks for the support!"
    color: "#F47FFF"
    thumbnail: "%user_avatar%"
    timestamp: true

Posts nothing if channels.welcome isn't set (no error, just silently skipped).

---

Sticky Roles — Automatically Restore Roles on Rejoin

If someone leaves the server and rejoins later, they automatically get their previous roles back without a mod having to reassign them manually.

NOT restored:

• @everyone (everyone has it anyway)
• Managed roles (owned by an integration/another bot, e.g. a Twitch sub role) — that integration reassigns it itself
• Roles that have since been deleted
• Roles that now sit above the bot's own highest role (Discord forbids this outright) — only that one role is skipped, the rest is still restored

Time window: Only within maxAgeDays (default 30 days) after leaving. After that, the role history is considered too stale/no longer relevant.

stickyRoles:
  enabled: true
  maxAgeDays: 30

---

/welcome — Admin Commands (Manage Guild)

Command	Function
/welcome preview	Welcome embed/banner using your own avatar
/welcome preview-leave	Random leave message
/welcome preview-verify	Verify panel preview
/welcome preview-captcha	Example image CAPTCHA
/welcome setup-verify	Re-posts the verify panel and saves the message ID
/welcome force-verify <user>	Skips the CAPTCHA, verifies immediately
/welcome reset <user>	Resets a user's active CAPTCHA session/cooldown
/welcome clear-lockdown	Manually ends an active raid lockdown
/welcome set-channel feature:verify-log channel:<#channel>	Sets the verify log channel
/welcome toggle feature:<join|leave|verification> enabled:<bool>	Toggles a feature on/off
/welcome show	Shows a summary of current settings
/welcome reload	Reloads configs/modules/welcome.yml

→ See also Preview-Commands-EN