Welcomer System

1. Feature Brief

The Welcomer plugin greets every new member with a unique, AI-generated message powered by Groq. Two welcome modes are available - a plain-text quip or a fully customisable rich embed - and up to five roles can be automatically assigned on join. All configuration is done through a GUI dashboard; no config files or re-running setup required.

1. AI-generated messages - each welcome message is uniquely generated by a Groq LLM; tone and style adapt automatically between Normal and Embed mode
2. Normal mode - a short, playful 5–8 word quip appended to a user mention, sent as plain text
3. Embed mode - a rich embed with a customisable title, description, colour, footer, thumbnail, and optional banner image or GIF
4. Placeholder system - embed fields support live placeholders that resolve to user, server, and AI content at send time
5. Auto role assignment - up to 5 roles are automatically granted to new members on join; deleted roles are self-healing and removed from config automatically
6. Per-server Groq API - each server provides its own Groq API key; keys are securely encrypted; the API key is validated live before saving
7. Fallback messages - if AI generation fails or no key is configured, the bot picks from a curated list of 22 fallback quips (Normal) or 12 warm sentences (Embed)
8. Test button - preview the exact welcome message or embed as the configuring admin before it goes live

Who can use this?

/welcomer setup and /welcomer admin both require Manage Server permission.

---

2. Sub-Systems

Welcome Modes

Two modes are available and switchable at any time from the admin dashboard - no re-setup needed.

Normal mode sends a plain text message in the format:

@User just joined! Hide your pizzas! 🍕

The AI generates a short, playful quip (5–8 words). The username is never included in the AI prompt - it is prepended as a mention in the final message.

Embed mode sends a rich embed alongside a user mention. The default embed includes:

• Title: Welcome {user} to {server}! 🎉
• Description: Hey {user.mention}! {ai_message}\n\nWe're so glad you're here. Make yourself at home!
• Color: #5865F2
• Author: username with avatar icon
• Timestamp: enabled

All embed fields are fully customisable via the Embed Style and Set Image/GIF modals.

Placeholders

Placeholders can be used in any embed text field (title, description, footer, author name). They are resolved at send time for each new member.

Placeholder	Resolves to
{user}	Member’s username
{user.mention}	@mention of the member
{user.tag}	Username with discriminator
{user.id}	Member’s user ID
{user.avatar}	Member’s avatar URL (256px)
{server}	Server name
{server.icon}	Server icon URL (256px)
{memberCount}	Current server member count
{ai_message}	The AI-generated (or fallback) welcome message

The {ai_message} placeholder is how the AI output is inserted into embed descriptions. If it is omitted from the description, the AI message is not shown in the embed.

AI Configuration

AI is powered by the Groq API and is opt-in - without a key the system uses built-in fallback messages.

Configure AI opens a 5-field modal:

Field	Default	Notes
Groq API Key	-	Required; validated live before saving
Custom System Prompt	Default prompt	Override the full AI instructions
AI Model	llama-3.1-8b-instant	Any Groq-supported model
Temperature	1.4	Must be between 0.1–2.0
Max Tokens	150	Controls response length

Default prompts differ by mode:

• Normal mode - instructs the AI to produce a 5–8 word playful quip, never including the username
• Embed mode - instructs the AI to produce a 1–2 sentence warm welcome sentence

A custom prompt fully replaces the default for both modes. If the AI returns an empty response or errors with an auth failure, the config auto-removes the invalid key and falls back to built-in messages.

Embed Customisation

Embed customisation is only available when Embed mode is active. Both buttons are disabled in Normal mode.

Embed Style modal (4 fields):

Field	Notes
Color	Hex format #RRGGBB; validated before saving
Title	Up to 256 characters; supports all placeholders
Description	Up to 2,000 characters; use {ai_message} to insert AI output
Footer	Up to 256 characters; supports {memberCount} and other placeholders

Set Image/GIF modal (2 fields):

Field	Options
Welcome Banner	A large image or GIF displayed at the bottom of the embed; must start with https://
Thumbnail (top-right)	Leave empty = user avatar (default) · Type none = no thumbnail · Paste URL = custom image

Banner URLs are validated to start with https://. Discord CDN links (cdn.discordapp.com) are recommended for best reliability; a tip is shown for non-CDN URLs.

Auto Role Assignment

Up to 5 roles can be assigned automatically to every new member on join. Roles are configured via a role select menu in the admin panel.

• Select 0 roles to clear all auto-assign roles
• The role select menu closes after 60 seconds of inactivity if no selection is made
• Roles are assigned in order; if a role no longer exists in the server it is silently removed from the config and skipped
• If role assignment fails due to a Missing Permissions error, the server owner is notified in the welcome channel with instructions to fix the role hierarchy
• The bot’s role must be positioned above any role it needs to assign in Server Settings → Roles

Role Hierarchy

The bot can only assign roles that sit below its own highest role. If auto-assignment silently fails, check that the bot’s role is above the target roles in the server’s role list.

Admin Dashboard

Run /welcomer admin to open the interactive dashboard. The admin panel closes after 5 minutes of inactivity.

Row 1 - Core Controls

Button	Action
Enable / Disable	Toggles the welcomer on or off; label and style update live
Switch to Embed / Normal	Toggles between welcome modes; initialises default embed config on first switch to Embed
Set Role	Opens a role select menu to configure auto-assign roles (up to 5)
Configure AI	Opens the 5-field AI configuration modal

Row 2 - Embed & Testing

Button	Active when	Action
Embed Style	Embed mode only	Opens the style modal (color, title, description, footer)
Set Image/GIF	Embed mode only	Opens the image modal (banner + thumbnail)
Test Message	Always	Sends a preview welcome to the admin as an ephemeral reply using their own username
Remove AI	When AI is configured	Removes the API key and all AI settings; reverts to fallback messages

The dashboard embed refreshes in place after every button action, showing the latest status, channel, mode, roles, AI status, model, image, color, and custom prompt state.

---

3. Setup

1. Run the setup command - use /welcomer setup channel:#your-welcome-channel to configure the welcome channel. The welcomer starts in Normal mode with no AI and no auto-roles.

2. Open the admin dashboard - run /welcomer admin to access all configuration options.

3. Configure AI Optional but Recommended - click Configure AI, enter your Groq API key, and optionally set a custom prompt, model, temperature, and token limit. The key is validated live - it will only save if it works.

4. Set auto-assign roles Optional - click Set Role and select up to 5 roles from the dropdown. Select none to clear.

5. Switch to Embed mode Optional - click Switch to Embed, then use Embed Style to customise the title, description, colour, and footer, and Set Image/GIF to add a banner or thumbnail.

6. Test - click Test Message to preview the exact output before a real member joins.

Settings Reference

Setting	Configured via	Default
Welcome Channel	/welcomer setup channel:	Required
Welcome Mode	Dashboard → Switch to Embed/Normal	Normal
Auto-Assign Roles	Dashboard → Set Role	None
Groq API Key	Dashboard → Configure AI	None (fallback messages)
AI Model	Dashboard → Configure AI	llama-3.1-8b-instant
Temperature	Dashboard → Configure AI	1.4
Max Tokens	Dashboard → Configure AI	150
Custom Prompt	Dashboard → Configure AI	Default mode prompt
Embed Color	Dashboard → Embed Style	#5865F2
Embed Banner	Dashboard → Set Image/GIF	None
Embed Thumbnail	Dashboard → Set Image/GIF	User avatar