Greeting System (Welcome & Farewell)
Relevant source files
The following files were used as context for generating this wiki page:
The Greeting System is a feature within Amina designed to automate personalized welcome and farewell messages when users join or leave a Discord server. This system enhances the onboarding and offboarding experience by allowing server administrators to configure custom messages, which can include simple text, rich embeds, and dynamic information about the member, server, and inviter.
Configuration is managed on a per-guild basis and stored in the database. The system is triggered by guildMemberAdd and guildMemberRemove events, which then use the greeting.ts handler to construct and dispatch the appropriate message to a designated channel. The status of these settings can be viewed using the /settings status command.
Sources: src/handlers/greeting.ts, src/commands/admin/settings/status.ts:43-50
System Architecture
The core logic resides in the greeting.ts handler, which is responsible for fetching guild-specific settings, parsing message content, building the final message payload (including embeds), and sending it to the configured channel.
High-Level Flow
The following diagram illustrates the process flow for both welcome and farewell events.
This diagram shows that when a user joins or leaves, the system checks if the corresponding greeting (welcome or farewell) is enabled for that server. If it is, it builds and sends the message.
Sources: src/handlers/greeting.ts:162-177, src/handlers/greeting.ts:182-196
Configuration
The greeting system's behavior is determined by the greeting and farewell objects within the guild's settings document in the database. These settings can be inspected using the /settings status command, which provides a summary of the current configuration.
Sources: types/schemas.d.ts:77-88, src/commands/admin/settings/status.ts:43-50
Schema Definition
The configuration for both welcome and farewell messages is defined by the GreetingConfig interface and stored within the IGuildSettings schema.
This ER diagram shows the greeting and farewell properties within the main IGuildSettings document, both of which use the GreetingConfig structure.
Sources: types/schemas.d.ts:77-88, src/handlers/greeting.ts:25-36
Configuration Fields
The table below details the fields available for configuring both welcome and farewell messages.
| Field | Type | Description |
|---|---|---|
enabled | boolean | Toggles the greeting message on or off. |
channel | string | The ID of the channel where messages will be sent. |
content | string | The plain text content of the message. Supports placeholders. |
embed | object | An object defining the structure of the embed. |
embed.description | string | The main text inside the embed. Supports placeholders. |
embed.color | string | The hex color code for the embed's side-bar. |
embed.thumbnail | boolean | If true, displays the member's avatar as a thumbnail. |
embed.footer | string | The footer text of the embed. Supports placeholders. |
embed.image | string | URL for a large image at the bottom of the embed. Supports placeholders. |
Sources: src/handlers/greeting.ts:25-36, types/schemas.d.ts:77-88
Message Generation
The greeting.ts handler contains the primary functions for creating and sending messages: sendWelcome and sendFarewell. These functions orchestrate the process of fetching data, building the message, and sending it.
Sequence Diagram for sendWelcome
This diagram shows the sequence of operations when a welcome message is sent. The flow for sendFarewell is identical.
Sources: src/handlers/greeting.ts:162-177
Message Parsing and Placeholders
The parse function is responsible for replacing placeholders in the message content and embed fields with dynamic data. This allows for highly personalized messages.
The following placeholders are available:
| Placeholder | Description | Example |
|---|---|---|
{server} | The name of the server. | Amina's Hangout |
{count} | The total member count of the server. | 1234 |
{member:nick} | The member's display name (nickname or username). | Mina |
{member:name} | The member's username. | mina |
{member:dis} | The member's discriminator (e.g., 0001). | 0001 |
{member:tag} | The member's full tag (username#discriminator). | mina#0001 |
{member:mention} | Mentions the member. | @mina |
{member:avatar} | The URL of the member's avatar. | https://cdn.discordapp.com/... |
{inviter:name} | The username of the person who invited the member. | vikshan |
{inviter:tag} | The full tag of the inviter. | vikshan#0001 |
{invites} | The total effective invites of the inviter. | 50 |
Sources: src/handlers/greeting.ts:51-100
Default Messages
If a greeting is enabled but no custom content or embed.description is provided, a default message is sent.
- Welcome:
Hey {user}, welcome to {server}! ✨ - Farewell:
It's sad to see you leave {server}, {user} 😢
These default strings are retrieved using mina.sayf(), indicating they are part of a centralized response system.
Sources: src/handlers/greeting.ts:143-156
Related Data Structures
The system relies on several interfaces to manage data passed between functions.
InviterData
This interface is used to pass information about the member who invited the new user. This is crucial for populating the {inviter:} and {invites} placeholders.
// From: src/handlers/greeting.ts:15-23
interface InviteData {
tracked?: number
added?: number
fake?: number
left?: number
}
interface InviterData {
member_id?: string
invite_data?: InviteData
}
Sources: src/handlers/greeting.ts:15-23
Summary
The Greeting System is a robust and flexible module for creating a welcoming environment in a Discord server. It leverages the bot's database-driven configuration to allow administrators to define custom welcome and farewell messages. With support for rich embeds and a wide range of dynamic placeholders, it can deliver personalized and informative greetings that reflect a server's unique identity. The logic is cleanly encapsulated within the greeting.ts handler, making it a modular and maintainable part of the Amina codebase.