# Broccolini Bot - New Features Documentation This document outlines all the features implemented in the latest update. --- ## Phase 1: Foundation & Core Commands ### 1. Variables System A powerful template system for dynamic messages using placeholders. **Available Variables:** - `{ticket.user}` / `{ticket.creator}` - Ticket creator username - `{ticket.email}` - Customer email address - `{ticket.number}` - Ticket number - `{ticket.subject}` - Ticket subject line - `{ticket.claimed}` - "Yes" or "No" - `{ticket.claimedby}` - Staff member name or "Unclaimed" - `{ticket.priority}` - Ticket priority level - `{staff.user}` - Staff username - `{staff.name}` - Staff display name - `{staff.mention}` - Staff mention (@user) - `{server.name}` - Discord server name - `{server.membercount}` - Server member count - `{hours}` - Hours (for auto-messages) - `{date}` - Current date - `{time}` - Current time **Usage:** Variables work in tags, welcome messages, and other customizable messages. --- ### 2. Tags/Saved Responses System Create, manage, and use saved responses for common questions. **Commands:** - `/response send ` - Send a saved response - `/response create ` - Create new saved response - `/response edit ` - Edit existing saved response - `/response delete ` - Delete a saved response - `/response list` - List all saved responses - `/tag` - Set ticket category (dropdown: Server Down, Billing, Mod Help, etc.); posts categorization message (channel name unchanged) **Features:** - Autocomplete support for response names - Usage counter tracking - Supports variable substitution - Database-backed persistence (MongoDB via Mongoose `Tag` model; see `models.js`) --- ### 3. User Management Commands #### `/add @user` Add a user to the current ticket thread. **Permissions:** Sets ViewChannel, SendMessages, and ReadMessageHistory for the user. #### `/remove @user` Remove a user from the current ticket thread. **Behavior:** Deletes the permission overwrite for the user. --- ### 4. `/help` Command Displays a comprehensive embed with all available commands, organized by category. **Categories:** - User Management - Ticket Management - Tags (Saved Responses) - Variables - Panel System - Other --- ## Phase 2: Ticket Management ### 1. `/transfer @staff [reason]` Transfer a ticket to another staff member. **Features:** - Validates target has staff role - Updates claimed_by in database - Logs to logging channel - Optional reason parameter --- ### 2. `/move #category` Move a ticket to a different category. **Features:** - Preserves permissions (lockPermissions: true) - Logs the move - Works with any category channel --- ### 3. `/force-close` Force close a ticket without confirmation. **Features:** - Generates transcript - Updates the external ticket API (if configured) - Archives channel after 5 seconds - No confirmation required --- ### 4. Close Confirmation System When clicking the "Close Ticket" button, users now see a confirmation prompt. **Flow:** 1. User clicks "Close Ticket" 2. Confirmation buttons appear (ephemeral) 3. User clicks "Confirm Close" or "Cancel" 4. If confirmed, ticket closes as usual **Storage:** Close requests are stored in MongoDB. See `models.js` for schema. --- ### 5. `/topic ` Set the channel topic/description for a ticket. **Use Cases:** - Document ticket status - Add important notes - Set expectations --- ## Phase 3: UX Enhancements ### 1. Enhanced Claiming System #### Claim Overwrite **Config:** `ALLOW_CLAIM_OVERWRITE=true/false` When enabled, allows staff to claim tickets already claimed by someone else. **Behavior:** - If disabled: Shows error message when trying to claim someone else's ticket - If enabled: Allows claim overwrite, updates claimed_by #### Auto-Unclaim on Inactivity **Config:** - `AUTO_UNCLAIM_ENABLED=true/false` - `AUTO_UNCLAIM_AFTER_HOURS=24` Automatically unclaims tickets after specified hours of inactivity. **Features:** - Checks every hour - Based on last_activity timestamp - Sends notification message in channel - Resets claimed_by to NULL #### Claim Timeout **Config:** - `CLAIM_TIMEOUT_ENABLED=true/false` - `CLAIM_TIMEOUT_HOURS=48` Set a maximum time for claims (future enhancement placeholder). --- ### 2. Modal Forms for Ticket Creation Users can create Discord-side tickets through an interactive modal form. **Form Fields:** - Subject (required, short text, max 100 chars) - Description (required, paragraph, max 1000 chars) - Priority (optional, low/normal/high) **Workflow:** 1. User clicks "Open Ticket" button on panel 2. Modal appears with form fields 3. User fills out and submits 4. Bot creates ticket channel automatically **Features:** - Validates priority input - Auto-generates ticket numbers - Sets proper permissions - Sends welcome message - Logs creation --- ### 3. Priority System #### `/priority ` Set ticket priority via dropdown: **low**, **normal**, **medium**, or **high** (default: normal). **Features:** - Dropdown choices: 🟢 Low, 🟡 Normal, 🟠 Medium, 🔴 High - When priority is set, the channel/thread name is prefixed with the priority emoji - Color-coded embeds - Database-backed - Visible in ticket embeds **Priority Colors:** - High: Red (#FF0000) - Normal / Medium: Info color - Low: Green (#00FF00) **Configuration:** ```env PRIORITY_ENABLED=true DEFAULT_PRIORITY=normal PRIORITY_HIGH_EMOJI=🔴 PRIORITY_MEDIUM_EMOJI=🟡 PRIORITY_LOW_EMOJI=🟢 ``` --- ## Phase 4: Panel & Category System ### 1. Panel System #### `/panel #channel [title] [description]` Create a ticket panel that users can interact with to open tickets. **Features:** - Customizable title and description - "Open Ticket" button - Sends modal form on click - Creates Discord-only tickets **Example Panel:** ``` Title: Open a Support Ticket Description: Click the button below to create a new support ticket. A staff member will assist you shortly. [🎫 Open Ticket] ``` --- ### 2. Discord-Side Tickets Tickets created through panels are Discord-only (no email integration). **Features:** - Stored in same tickets table - gmail_thread_id uses format: `discord-{timestamp}-{userId}` - sender_email contains Discord tag - Full feature parity with email tickets --- ### 3. Category System The bot now supports multiple categories through the `/move` command. **Features:** - Move tickets between categories - Preserves permissions - Works with both email and Discord tickets --- ### 4. Thread-Style Tickets **Config:** - `USE_THREADS=true/false` - `THREAD_PARENT_CHANNEL=` When enabled, creates tickets as threads instead of channels. **Benefits:** - Cleaner server structure - No channel limit concerns - Better organization **Note:** Implementation ready for future activation. --- ## Phase 5: Automation (Future Enhancement) ### Automation Rules Engine A framework for creating custom automation rules. **Planned Features:** - Trigger-based actions - Condition matching - Custom workflows - Schedule support **Example Rules:** - Auto-assign based on keywords - Auto-tag based on content - Auto-escalate high priority - Auto-move based on game/topic **Note:** Foundation in place, specific rules to be implemented based on needs. --- ## Database Schema The project uses MongoDB. Ticket, tag, and close-request data are defined in `models.js`. See that file and `MONGODB_SETUP.md` for schema reference. --- ## Configuration Reference ### New Environment Variables ```env # --- CLAIMING OPTIONS --- CLAIM_TIMEOUT_ENABLED=false CLAIM_TIMEOUT_HOURS=48 AUTO_UNCLAIM_ENABLED=false AUTO_UNCLAIM_AFTER_HOURS=24 ALLOW_CLAIM_OVERWRITE=false # --- THREAD-STYLE TICKETS --- USE_THREADS=false THREAD_PARENT_CHANNEL= ``` --- ## Complete Command Reference ### User Management - `/add @user` - Add user to ticket - `/remove @user` - Remove user from ticket ### Ticket Management - `/transfer @staff [reason]` - Transfer ticket to another staff member - `/move #category` - Move ticket to another category - `/force-close` - Force close without confirmation - `/topic ` - Set channel topic - `/priority ` - Set ticket priority (low/normal/medium/high); renames channel with priority emoji - `/escalate [reason] [tier]` - Escalate ticket to tier 2 or 3 - `/deescalate` - De-escalate ticket ### Tags / Saved Responses - `/response send ` - Send saved response - `/response create ` - Create new saved response - `/response edit ` - Edit existing saved response - `/response delete ` - Delete saved response - `/response list` - List all saved responses - `/tag` - Set ticket category (dropdown) ### Panel System - `/panel #channel [title] [description]` - Create ticket panel ### Help - `/help` - Show all commands --- ## Migration Notes ### From Previous Version 1. **Database**: New Mongoose schema fields used on startup (collections created as needed) - priority, last_activity, reminder_sent on Ticket 2. **New collections**: Created automatically by Mongoose - Tag (saved responses) - CloseRequest 3. **Environment Variables**: Add to `.env` (repo root): ```env CLAIM_TIMEOUT_ENABLED=false AUTO_UNCLAIM_ENABLED=false ALLOW_CLAIM_OVERWRITE=false USE_THREADS=false ``` 4. **No Breaking Changes**: All existing functionality preserved --- ## Best Practices ### Tags - Use descriptive names (e.g., `welcome`, `closing`, `escalation-info`) - Include variables for personalization - Keep content concise but helpful - Review and update regularly ### Priority System - Set priority early in ticket lifecycle - Use high priority sparingly - Review priority regularly - Consider SLA based on priority ### Panels - Place in dedicated support channels - Use clear, welcoming language - Include instructions - Monitor for spam/abuse ### Claiming - Enable auto-unclaim to prevent stale claims - Set reasonable timeout periods - Use overwrite cautiously - Communicate with team about transfers --- ## Troubleshooting ### Commands Not Appearing - Verify `DISCORD_APPLICATION_ID` is set - Check bot has application.commands scope - Wait up to 1 hour for Discord to sync - Restart bot after .env changes ### Modal Not Showing - Ensure user has Create Posts permission - Check for Discord outages - Verify bot has proper permissions ### Saved Responses Not Working - Check MongoDB connection and permissions - Use `/response list` to confirm saved response exists - Check for errors in saved response content ### Priority Not Updating - Verify ticket exists in database - Check PRIORITY_ENABLED is true - Ensure valid priority value (low/normal/high) --- ## Performance Considerations ### Database - MongoDB (Mongoose) for all persistent data - Regular backups recommended - Run from repo root; `.env` in repo root ### Auto-Checks - Auto-close: Runs every hour - Auto-unclaim: Runs every hour - Reminders: Runs every 30 minutes - Adjust intervals in code if needed ### Rate Limits - Channel creation: 50/day per guild - Channel rename: 2 per 10 minutes per channel ([Discord docs](https://discord.com/developers/docs/topics/rate-limits)). When the limit is reached, the bot skips the rename and posts: *Channel renamed too quickly. Try again \.* - Message edits: Be cautious with bulk operations --- ## Future Enhancements ### Planned Features 1. **Statistics Dashboard**: Track ticket metrics 2. **Feedback System**: Collect user ratings 3. **Advanced Automations**: Rule builder UI 4. **Ticket Templates**: Pre-filled forms 5. **SLA Tracking**: Response time monitoring 6. **Multi-language**: Localization support 7. **Web Dashboard**: View tickets in browser 8. **API Endpoints**: External integrations ### Community Requests - Custom ticket categories per game - User blacklist system - Scheduled availability hours - Ticket assignment rotation - Knowledge base integration --- ## Support & Contributing ### Getting Help - Check documentation first - Review troubleshooting section - Check logs for error messages - Test with minimal configuration ### Reporting Bugs Include: - Steps to reproduce - Expected behavior - Actual behavior - Environment details - Log excerpts ### Feature Requests Consider: - Use case description - Priority/importance - Potential workarounds - Similar existing features --- ## Changelog ### v2.0.0 - Major Feature Update **Added:** - Variables system for dynamic messages - Tags/saved responses system - User management commands (/add, /remove) - Transfer, move, force-close commands - Close confirmation flow - Enhanced claiming (overwrite, auto-unclaim) - Modal forms for ticket creation - Priority system - Panel system for Discord tickets - Thread-style tickets option - Comprehensive /help command **Improved:** - Database schema with new fields - Permission handling - Error messages - Logging **Fixed:** - Various edge cases - Permission issues - Database constraints --- *Last Updated: 2025* *Version: 2.0.0*