broccolini-bot/docs/setup/QUICKSTART.md

Broccolini Bot – Quick Start Guide

Get started with Broccolini Bot in 5 minutes! Run all commands from the repo root. Ensure .env exists in the repo root (copy from .env.example).

Test env: To try changes safely, use .env.test (copy from .env.test.example) and run npm run start:test. See ENV_AND_SECURITY.md. Agents: do not modify .env without explicit user confirmation; prefer changing .env.test first.

1. Restart Your Bot

npm start

The bot will automatically:

• Use MongoDB collections (Tag, CloseRequest, etc.) as needed
• Register all new slash commands
• Start background jobs (auto-close, auto-unclaim, reminders)

2. Create Your First Saved Response

/response create name:welcome content:Welcome to support, {ticket.user}! We'll help you with {ticket.subject}.

Then use it:

/response send name:welcome

Use /tag in a ticket channel to set the ticket category (dropdown: Server Down, Billing, Mod Help, etc.). The bot posts: Your ticket has been categorized as [Emoji][Tag][Emoji].

3. Set Up a Ticket Panel

/panel #support-tickets type:both title:Need Help? description:Click below to open a ticket!

Use type to choose thread, category, or both. Users click the button → Fill out modal → Ticket created automatically!

4. Try the New Commands

User Management

/add @user           # Add someone to current ticket
/remove @user        # Remove someone from ticket

Ticket Actions

/transfer @staff     # Transfer to another staff member
/move #category      # Move to different category
/priority [level]    # Set priority: posts upgraded/downgraded/normal message; email sent when set to high
/topic Important!    # Set channel topic
/escalate [reason] [tier]  # Escalate to tier 2 or 3 (or use Escalate button)
/deescalate         # De-escalate one step
/force-close        # Close without confirmation

Close Confirmation

Click "Close Ticket" button → Get confirmation prompt → Confirm or cancel

5. Configure New Options

Edit your .env:

# Enable auto-unclaim after 24 hours of inactivity
AUTO_UNCLAIM_ENABLED=true
AUTO_UNCLAIM_AFTER_HOURS=24

# Allow staff to claim already-claimed tickets
ALLOW_CLAIM_OVERWRITE=true

# Use threads instead of channels (future)
USE_THREADS=false

Restart the bot after changing .env; slash commands may need re-registration (restart the bot).

6. Use Variables in Tags

Create smart tags with dynamic content:

/response create name:closing content:Thanks {ticket.user}! Ticket #{ticket.number} is now closed. Contact us anytime at {server.name}!

Available variables:

• {ticket.user}, {ticket.email}, {ticket.number}, {ticket.subject}
• {staff.name}, {staff.mention}
• {server.name}, {date}, {time}

7. Priority Management

Set priorities for better organization:

/priority low      # 🟢 Low priority
/priority normal   # 🟡 Normal (default)
/priority medium   # 🟠 Medium priority
/priority high     # 🔴 High priority (sends email to ticket sender)

The bot posts: Your ticket has been upgraded/downgraded to [Emoji][Level][Emoji]. or Your ticket priority has returned to Normal.

8. Test the Panel System

1. Create panel in a channel: /panel #support
2. As a user, click "Open Ticket" button
3. Fill out the modal form
4. Submit → Ticket channel created automatically!

9. View All Commands

/help

Shows organized list of all commands with descriptions.

10. Check Your Setup

Verify everything is working:

✅ All slash commands appear in Discord ✅ Can create saved responses with /response create; use /tag for ticket category ✅ Panel shows "Open Ticket" button (and optional type: thread / category / both) ✅ Clicking button shows modal form ✅ Close button shows confirmation ✅ Priority command updates ticket ✅ /help command shows all features

---

Common Issues

Commands not showing?

• Wait up to 1 hour for Discord to sync
• Verify DISCORD_APPLICATION_ID in .env
• Restart bot

Modal not appearing?

• Check user permissions
• Ensure bot has proper guild permissions
• Try in different channel

Saved responses not working?

• Use /response list to see all tags
• Check for typos in tag name
• Autocomplete shows valid tags

---

Next Steps

1. Create More Tags: Add responses for common questions
2. Set Up Panels: Put panels in help channels
3. Train Staff: Show team the new commands
4. Enable Auto-Features: Turn on auto-unclaim if desired
5. Customize Messages: Edit .env variables for your brand
6. Monitor Performance: Check logs for errors

---

Key Features Summary

✨ Variables - Dynamic message templates
🏷️ Tags - Saved responses system
👥 User Management - Add/remove users from tickets
🎫 Panel System - User-friendly ticket creation
📋 Modal Forms - Interactive ticket submission
⚡ Priority Levels - Organize by importance
🔄 Transfer - Move tickets between staff
📌 Enhanced Claiming - Auto-unclaim, overwrite options
✅ Close Confirmation - Prevent accidental closes
📚 Help Command - Built-in documentation

---

Pro Tips

💡 Use variables in welcome messages for personalization
💡 Create tags for FAQs to save time
💡 Set high priority for urgent tickets
💡 Use /topic to document ticket status
💡 Enable auto-unclaim to prevent stale claims
💡 Put panels in pinned messages
💡 Use /transfer with reasons for context

---

Getting Help

• Read PHASE_FEATURES.md for detailed documentation
• Check logs for error messages
• Test features in a test channel first
• Use /help in Discord for command reference

---

Ready to go! Enjoy your enhanced ticket system! 🚀