200 lines
5.8 KiB
Markdown
200 lines
5.8 KiB
Markdown
# 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](./ENV_AND_SECURITY.md). **Agents:** do not modify `.env` without explicit user confirmation; prefer changing `.env.test` first.
|
||
|
||
## 1. Restart Your Bot
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```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](./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! 🚀**
|