Ticket System

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/admin/ticket.ts
• src/handlers/ticket/main-hub.ts
• src/handlers/ticket/shared/buttons.ts
• src/handlers/ticket/shared/utils.ts
• src/handlers/ticket/setup/menu.ts
• src/handlers/ticket/setup/message.ts
• src/handlers/ticket/setup/topics.ts
• src/handlers/ticket/manage/menu.ts
• src/handlers/ticket/manage/addUser.ts
• src/events/interactions/interactionCreate.ts
• src/data/respTicket.json

The Ticket System is a comprehensive feature within Amina that allows server members to create private support channels, called tickets, to communicate with staff. Administrators have extensive control over the system's configuration, including setting up ticket creation messages, defining support topics, managing ticket access, and logging ticket activity.

The system is primarily managed through the /ticket command, which provides a centralized hub for all setup and management operations. It is designed to be interactive, guiding administrators through setup with a series of menus, modals, and selection components.

Architecture and Core Concepts

The ticket system is event-driven, relying on Discord's interaction system (buttons, select menus, modals) to function. All interactions are routed through a central handler which dispatches them to the appropriate ticket module.

Sources: src/commands/admin/ticket.ts, src/events/interactions/interactionCreate.ts:281-337

Interaction Routing

The interactionCreate.ts event listener is the entry point for all ticket-related interactions. It filters interactions based on their customId and delegates them to specific handlers within the src/handlers/ticket/ directory.

The diagram below illustrates the routing logic for ticket interactions.

Sources: src/events/interactions/interactionCreate.ts:281-432, src/commands/admin/ticket.ts:16-22

Ticket Channel Identification

A text channel is identified as a ticket channel based on two properties:

1. Channel Name: Must start with the prefix tіcket-.
2. Channel Topic: Must start with tіcket| and follow the format tіcket|{user.id}|{catName}.

This structure allows the system to easily find all ticket channels, identify the user who opened the ticket, and determine its topic.

Sources: src/handlers/ticket/shared/utils.ts:22-28, src/handlers/ticket/shared/buttons.ts:200-202

Configuration Data

Ticket system settings are stored on a per-guild basis within the Guild schema. Key configuration fields under the ticket object include:

Field	Type	Description	Source File
enabled	Boolean	Toggles the entire ticket system.	src/handlers/ticket/setup/message.ts:208
limit	Number	The maximum number of open tickets allowed in the server.	src/handlers/ticket/shared/buttons.ts:45
category	String (ID)	The Discord Category ID where new ticket channels are created.	src/handlers/ticket/setup/message.ts:145
log_channel	String (ID)	The channel ID where ticket closure logs are sent.	src/handlers/ticket/shared/utils.ts:220
topics	Array	An array of topic objects, each with a name property.	src/handlers/ticket/setup/topics.ts:29
setup_message_id	String (ID)	The ID of the message containing the "open a ticket" button.	src/handlers/ticket/setup/message.ts:227

Sources: src/handlers/ticket/shared/buttons.ts, src/handlers/ticket/setup/topics.ts, src/handlers/ticket/setup/message.ts

Ticket Lifecycle

1. Creation

A user initiates ticket creation by clicking a button with the customId TICKET_CREATE. This triggers a sequence of events to create a private and organized support channel.

The following diagram details the ticket creation flow:

Sources: src/handlers/ticket/shared/buttons.ts:31-278

2. Management

Once a ticket is open, staff can perform management actions through the /ticket command, which opens the main hub. Selecting "Manage" from the hub presents several options.

• Add/Remove Users: Staff can grant or revoke access to the ticket channel for specific users. The system presents a user selection menu and then updates the channel's permission overwrites.
  Sources: src/handlers/ticket/manage/addUser.ts:59-152
• Close Ticket: Closes the current ticket channel.
• Close All Tickets: A bulk operation to close all open tickets in the server.

3. Closure & Deletion

The closeTicket utility function orchestrates the ticket closure process.

Sources: src/handlers/ticket/shared/utils.ts:74-252

After a ticket is closed, the channel is locked. A final "Delete Channel" button is presented. Clicking this button triggers handleTicketDelete, which permanently removes the channel from the server.

Sources: src/handlers/ticket/shared/buttons.ts:340-429

Administrator Setup

Server administrators can configure the ticket system using the /ticket command. This command opens an interactive hub.

Sources: src/commands/admin/ticket.ts:16-22, src/handlers/ticket/main-hub.ts:15-41

Main Hub Navigation

The main hub allows navigation between "Setup" and "Manage" functionalities.

Sources: src/handlers/ticket/main-hub.ts, src/handlers/ticket/setup/menu.ts, src/handlers/ticket/manage/menu.ts

Setup Options

Message Setup

This flow allows an admin to create the initial message that users will interact with to open a ticket.

1. Admin selects a text channel for the message.
2. A modal appears to customize the embed's title, description, and footer.
3. The bot sends the configured embed to the selected channel with an "open a ticket" button.
4. The bot saves the message ID to the guild's settings.

Sources: src/handlers/ticket/setup/message.ts:20-234

Topic Management

Topics help categorize tickets. Each topic is linked to a Discord Category, ensuring tickets for a specific topic are grouped together.

1. Add Topic: An admin provides a topic name (e.g., "Billing Support"). The system:
   • Adds the topic to the guild's settings.
   • Creates a new Discord Category with the same name.
   • Sets permissions on the category to be visible only to staff and the bot.
2. Remove Topic: An admin selects a topic to remove. The system:
   • Removes the topic from the guild's settings.
   • Deletes the corresponding Discord Category.
3. List Topics: Displays all currently configured topics.

Sources: src/handlers/ticket/setup/topics.ts:22-446

Other Settings

• Log Channel: Admins can designate a channel where a log message is sent every time a ticket is closed.
• Ticket Limit: Admins can set a server-wide limit on the number of concurrently open tickets. The minimum limit is 5.

Sources: src/commands/admin/ticket/setup.ts:140-161

Summary

The Amina Ticket System is a powerful and flexible module for managing user support on a Discord server. Its interactive setup process, topic-based categorization, and automated lifecycle management (creation, logging, closure) provide a streamlined experience for both users and staff. The architecture, centered around Discord interactions and a central routing handler, makes it an extensible and robust feature.