indifferentketchup/broccolini-bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
29a13768f7adc81f134222a9777c850b4ffeff1d
broccolini-bot/docs/PHASE_FEATURES.md

13 KiB
Raw Blame History

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 <name> - Send a saved response
  • /response create <name> <content> - Create new saved response
  • /response edit <name> <content> - Edit existing saved response
  • /response delete <name> - 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 <text>

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 <level>

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:

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=<channel_id>

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

# --- 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 <text> - Set channel topic
  • /priority <level> - 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 <name> - Send saved response
  • /response create <name> <content> - Create new saved response
  • /response edit <name> <content> - Edit existing saved response
  • /response delete <name> - 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):

    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). When the limit is reached, the bot skips the rename and posts: Channel renamed too quickly. Try again <t:unlock:R>.
  • 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

Reference in New Issue View Git Blame Copy Permalink