First upload
This commit is contained in:
samkintop
199
docs/setup/QUICKSTART.md
Normal file
199
docs/setup/QUICKSTART.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# 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! 🚀**
|
||||
Reference in New Issue
Block a user