firefrost-gaming/firefrost-operations-manual
3
0
Fork 0
Code Issues 146 Pull Requests Packages Projects Releases Wiki Activity

docs: add comprehensive Ticket Tool setup guide

Browse Source 
WHAT WAS DONE:
- Created docs/guides/ticket-tool-setup-guide.md
- 10-step installation and configuration guide for Ticket Tool
- Documents all 6 ticket categories with rationale for each
- Includes complete panel configuration (welcome messages, routing,
  naming, permissions) for every ticket type
- Transcript and logging setup
- Staff workflow reference
- Troubleshooting section (including role hierarchy lesson learned today)
- Future enhancements roadmap
- References Task #85 (Paymenter redirect)

TICKET CATEGORIES:
1. Billing & Subscriptions (💳)
2. Server Help (🎮)
3. Technical Issues (🔧)
4. Report a Player (🚨)
5. Sales & Upgrades (💎)
6. Suggestions & Feedback (💡)

WHY:
Decision made this session: all support lives in Discord.
Paymenter built-in ticket system will be bypassed (Task #85).
Complete guide means anyone on the team can set this up
without needing Michael present.

FILES ADDED:
- docs/guides/ticket-tool-setup-guide.md

Signed-off-by: Chronicler #45 <claude@firefrostgaming.com>
This commit is contained in:
Claude (Chronicler #45)
2026-03-28 21:05:50 +00:00
parent 9eb124a76d
commit 54d615e7f0
1 changed files with 411 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

411
docs/guides/ticket-tool-setup-guide.md Normal file
View File

@@ -0,0 +1,411 @@
# Ticket Tool — Complete Setup Guide
**For:** Firefrost Gaming Discord Server
**Created:** March 28, 2026
**Created By:** Chronicler #45
**Bot:** Ticket Tool (tickettool.xyz)
**Guild ID:** `1260574715546701936`
**Status:** Ready to implement
---
## 📖 OVERVIEW
Ticket Tool is the official support ticketing system for Firefrost Gaming. All support requests — whether they originate from the website, Paymenter billing portal, or Discord itself — funnel through a single Discord ticket system. This gives Meg and staff one queue to manage, one place to check, one workflow to follow.
**Ticket Tool handles:**
- Private ticket channels created on demand by subscribers and Wanderers
- Categorized routing (billing vs technical vs gameplay vs suggestions)
- Automatic transcripts saved when tickets close
- Staff claiming so one person owns each ticket
- Clean close/archive flow
---
## 🗂️ TICKET CATEGORIES
These are the six ticket types members can open. Names are chosen for speed — a member should be able to read the list and immediately know which one to pick.
| # | Button Label | Emoji | Who Uses It | What It's For |
|---|-------------|-------|-------------|---------------|
| 1 | **Billing & Subscriptions** | 💳 | Anyone | Payment issues, subscription questions, refunds, tier changes, account access |
| 2 | **Server Help** | 🎮 | Subscribers | Can't connect, crashes, lag, whitelist issues, in-game bugs |
| 3 | **Technical Issues** | 🔧 | Anyone | Launcher problems, mod errors, Java issues — anything not server-specific |
| 4 | **Report a Player** | 🚨 | Anyone | Rule violations, harassment, griefing, cheating |
| 5 | **Sales & Upgrades** | 💎 | Wanderers / Subscribers | Questions before subscribing, tier comparisons, what's included |
| 6 | **Suggestions & Feedback** | 💡 | Anyone | Server ideas, modpack requests, Discord improvements, general feedback |
### Why These Categories
- **Billing & Subscriptions** is first because it's the most urgent — money issues get answered fast
- **Server Help** vs **Technical Issues** splits gameplay problems (server-side) from client problems (their machine) — routes to different staff knowledge
- **Report a Player** is clearly labeled so members don't bury it in general support
- **Sales & Upgrades** gives Wanderers a non-committal way to ask questions before subscribing — this is a conversion tool as much as a support tool
- **Suggestions & Feedback** replaces a suggestions channel — staff can respond properly and close it when actioned
---
## 🛠️ STEP 1: INVITE TICKET TOOL
1. Go to: **https://tickettool.xyz**
2. Click **"Add to Server"** or **"Invite"**
3. Select **Firefrost Gaming** from the server dropdown
4. Grant the requested permissions — Ticket Tool needs:
- Manage Channels (creates ticket channels)
- Manage Roles (for ticket permissions)
- Read/Send Messages
- Embed Links
- Attach Files
- Manage Messages (for pinning/deleting)
- Read Message History
- Add Reactions
5. Click **Authorize**
6. Complete the CAPTCHA if prompted
Ticket Tool will appear in your member list as a bot.
---
## 🏗️ STEP 2: POSITION TICKET TOOL IN ROLE HIERARCHY
Just like Carl-bot, Ticket Tool needs its role above the roles it manages.
1. Go to **Server Settings → Roles**
2. Find **Ticket Tool** in the role list
3. Drag it **above** Wanderer, and above all subscriber tier roles
4. It does NOT need to be above Staff/Moderator roles
5. Save
> **Lesson learned:** Gray role icons in bot dashboards = hierarchy problem. Ticket Tool creates channels with role permissions — if its role is too low, channel creation silently fails.
---
## ⚙️ STEP 3: ACCESS THE TICKET TOOL DASHBOARD
1. Go to: **https://tickettool.xyz/dashboard**
2. Log in with your Discord account (Michael or Meg)
3. Select **Firefrost Gaming** from your server list
4. You're now in the Ticket Tool control panel
All configuration happens here. You don't need to run any bot commands in Discord.
---
## 📍 STEP 4: CREATE THE TICKET PANEL CHANNEL
Before configuring Ticket Tool, create the channel where the support panel will live.
**In Discord:**
1. Go to your **Support** category
2. Create a new text channel: **`#open-a-ticket`**
3. Set channel permissions:
- **@everyone / Wanderer:** View Channel ✅ — Send Messages ❌
- **Staff/Moderator:** Full access ✅
4. Pin a message in the channel (before deploying the panel):
```
🎟️ Need help? Click a button below to open a support ticket.
A private channel will be created just for you and our staff.
Our team typically responds within a few hours.
```
> Staff-only channels for ticket transcripts and logs will be created in Step 7.
---
## 🎛️ STEP 5: CONFIGURE SUPPORT ROLES
Tell Ticket Tool which roles can see and respond to tickets.
**In Ticket Tool Dashboard → Settings → Support Roles:**
Add these roles as support agents:
- **Wizard** (Michael)
- **Emissary** (Meg)
- **Moderators**
- **Staff** (general staff role if it exists)
These roles will automatically have access to every ticket channel when it's created.
---
## 🎟️ STEP 6: CREATE THE TICKET PANEL
This is the panel with buttons that members click to open tickets.
**In Ticket Tool Dashboard → Panels → Create Panel:**
### Panel Settings
| Setting | Value |
|---------|-------|
| Channel | `#open-a-ticket` |
| Panel Title | `Firefrost Gaming Support` |
| Panel Description | `Select the category that best matches your issue. A private ticket will open instantly.` |
| Panel Color | `#3B82F6` (Frost blue) or `#EF4444` (Fire red) — your choice |
| Thumbnail | Firefrost Gaming logo (optional) |
### Create Each Ticket Category
Click **"Add Ticket Type"** for each of the six categories below.
---
#### 💳 Billing & Subscriptions
| Field | Value |
|-------|-------|
| Name | `Billing & Subscriptions` |
| Emoji | 💳 |
| Button Color | Green |
| Welcome Message | `Thanks for reaching out about billing. Please describe your issue and include your subscription email address. A staff member will be with you shortly.` |
| Support Roles | Wizard, Emissary |
| Category (Discord) | Support (or create a `🎟️ Tickets` category) |
| Ticket Name Format | `billing-{username}` |
| Max Open Tickets Per User | 1 |
---
#### 🎮 Server Help
| Field | Value |
|-------|-------|
| Name | `Server Help` |
| Emoji | 🎮 |
| Button Color | Blurple |
| Welcome Message | `Thanks for reaching out! Please tell us: which server you're playing on, what happened, and any error messages you saw. Screenshots help a lot.` |
| Support Roles | Wizard, Emissary, Moderators, Staff |
| Category (Discord) | Support / Tickets |
| Ticket Name Format | `server-{username}` |
| Max Open Tickets Per User | 1 |
---
#### 🔧 Technical Issues
| Field | Value |
|-------|-------|
| Name | `Technical Issues` |
| Emoji | 🔧 |
| Button Color | Blurple |
| Welcome Message | `Thanks for reaching out! Please describe the issue, what you've already tried, and include your Java version and launcher (CurseForge, Prism, FTB, etc.). Screenshots or error logs are super helpful.` |
| Support Roles | Wizard, Emissary, Moderators, Staff |
| Category (Discord) | Support / Tickets |
| Ticket Name Format | `tech-{username}` |
| Max Open Tickets Per User | 1 |
---
#### 🚨 Report a Player
| Field | Value |
|-------|-------|
| Name | `Report a Player` |
| Emoji | 🚨 |
| Button Color | Red |
| Welcome Message | `Thank you for reporting. This ticket is private — only you and staff can see it. Please provide: the player's username, what happened, when it happened, and any screenshots or evidence you have.` |
| Support Roles | Wizard, Emissary, Moderators |
| Category (Discord) | Support / Tickets |
| Ticket Name Format | `report-{username}` |
| Max Open Tickets Per User | 2 |
---
#### 💎 Sales & Upgrades
| Field | Value |
|-------|-------|
| Name | `Sales & Upgrades` |
| Emoji | 💎 |
| Button Color | Green |
| Welcome Message | `Thinking about subscribing or upgrading? Excellent taste. Ask us anything — what's included in each tier, which path suits you, or how to upgrade. We're happy to help you find the right fit.` |
| Support Roles | Wizard, Emissary |
| Category (Discord) | Support / Tickets |
| Ticket Name Format | `sales-{username}` |
| Max Open Tickets Per User | 1 |
---
#### 💡 Suggestions & Feedback
| Field | Value |
|-------|-------|
| Name | `Suggestions & Feedback` |
| Emoji | 💡 |
| Button Color | Grey |
| Welcome Message | `We love hearing from the community! Share your idea or feedback and we'll review it. We read every single one — your ideas shape what Firefrost becomes.` |
| Support Roles | Wizard, Emissary, Moderators, Staff |
| Category (Discord) | Support / Tickets |
| Ticket Name Format | `feedback-{username}` |
| Max Open Tickets Per User | 1 |
---
## 📋 STEP 7: CONFIGURE TRANSCRIPTS & LOGGING
When a ticket closes, you want a record of it.
**In Ticket Tool Dashboard → Settings → Logs:**
1. Create a staff-only channel in Discord: **`#ticket-logs`**
- Only Staff / Moderator roles can see it
- Wanderers and subscribers cannot see it
2. Set **Transcript Channel** → `#ticket-logs`
3. Set **Log Channel** → `#ticket-logs` (same channel is fine for small teams)
4. Enable:
- ✅ Log ticket creation
- ✅ Log ticket closure
- ✅ Save transcript on close
- ✅ DM transcript to user on close (optional but nice — users get a record)
---
## 🔒 STEP 8: TICKET CHANNEL PERMISSIONS
By default, Ticket Tool creates a private channel that only the opener and support roles can see. Verify these defaults in **Dashboard → Settings → Permissions:**
- ✅ Ticket creator can view and send messages
- ✅ Support roles can view and send messages
- ✅ @everyone / Wanderer **cannot** view ticket channels
- ✅ Other subscribers **cannot** view other members' tickets
This is already the default behavior — just confirm it's set correctly.
---
## 🧪 STEP 9: TEST BEFORE GOING LIVE
Before announcing to the community, run through the full lifecycle.
### Test Flow
1. **Create a test ticket** — Click each of the 6 buttons as yourself or a test account
2. **Verify the channel appears** — Private channel created in the right category
3. **Verify welcome message** — Correct message for that ticket type
4. **Verify staff can see it** — Log in as Meg or another staff account and confirm visibility
5. **Close the ticket** — Use the close button in the ticket channel
6. **Verify transcript** — Check `#ticket-logs` for the saved transcript
7. **Repeat for all 6 categories**
### What to Check
- [ ] All 6 ticket types create channels correctly
- [ ] Channel names follow the format (e.g., `billing-frostystyle`)
- [ ] Welcome messages are correct for each type
- [ ] Staff roles can see all ticket channels
- [ ] Wanderers/subscribers cannot see other people's tickets
- [ ] Closing a ticket saves a transcript to `#ticket-logs`
- [ ] The panel in `#open-a-ticket` looks clean and professional
---
## 📢 STEP 10: UPDATE SUPPORT TOUCHPOINTS
Once Ticket Tool is live and tested, update everywhere that previously mentioned support:
### Ghost Website Contact Page
The Contact page (already published by The Publisher, Chronicler #39) should link directly to Discord with a note about tickets:
> "Need help? Join our Discord and open a support ticket — our team responds within a few hours."
Add a Discord invite button/link on the Contact page.
### Paymenter Billing Portal
See **Task #85** — modify Paymenter's support page to redirect to Discord instead of Paymenter's built-in ticket system. The exact method (link swap vs template edit) depends on what the Paymenter admin panel looks like — investigate when on desktop.
### Discord Welcome Channel
Update `#welcome` or `#rules` to mention: "Need help? Open a ticket in `#open-a-ticket`."
### Wanderer Onboarding
If Carl-bot sends a welcome DM (future enhancement), include the ticket channel link.
---
## 🔄 TICKET WORKFLOW FOR STAFF
### Standard Flow
```
Member opens ticket
↓
Staff sees new channel appear in ticket category
↓
Staff member "claims" the ticket (assigns to themselves)
↓
Conversation happens in the private channel
↓
Issue resolved
↓
Staff closes ticket
↓
Transcript saved to #ticket-logs
↓
Channel archived/deleted
```
### Staff Commands (in ticket channel)
Most actions happen via buttons Ticket Tool pins in the channel, but common slash commands:
| Command | What It Does |
|---------|-------------|
| `/close` | Closes the ticket, saves transcript |
| `/add @user` | Adds someone else to the ticket (e.g., Michael for billing escalation) |
| `/remove @user` | Removes someone from the ticket |
| `/rename [name]` | Renames the ticket channel |
| `/transcript` | Generates transcript manually without closing |
---
## 🚨 TROUBLESHOOTING
### Ticket channels not being created
**Symptom:** Member clicks button, nothing happens
**Cause:** Ticket Tool's role is below the Discord category in the hierarchy, OR missing Manage Channels permission
**Fix:** Server Settings → Roles → drag Ticket Tool role higher. Verify Manage Channels permission is granted.
### Members can see other people's tickets
**Cause:** Channel permissions misconfigured — @everyone has View Channel allowed somewhere
**Fix:** Dashboard → Settings → Permissions — ensure @everyone is denied View Channel for ticket channels
### Transcripts not saving
**Cause:** Ticket Tool bot doesn't have permission to send messages in `#ticket-logs`
**Fix:** Check `#ticket-logs` channel permissions — Ticket Tool role needs Send Messages and Attach Files
### Wrong welcome message showing
**Cause:** Panel wasn't saved after editing the ticket type
**Fix:** Dashboard → Panels → edit the ticket type → Save Changes → Redeploy Panel
---
## 📊 FUTURE ENHANCEMENTS
Once the basic system is running smoothly, consider:
1. **Auto-close inactive tickets** — Close tickets with no activity after 7 days with a warning message first
2. **Ticket claiming** — Require staff to "claim" before responding (prevents double-handling)
3. **Pre-ticket questions** — Require members to answer 2-3 questions before the ticket opens (e.g., "Which server?" for Server Help tickets) — reduces back-and-forth
4. **Working hours message** — Auto-reply after hours: "We've received your ticket and will respond within 24 hours"
5. **CSAT rating** — After ticket closes, ask the member to rate their support experience
---
## 📝 NOTES
- Ticket Tool's free tier is sufficient for Firefrost at launch. Premium adds things like custom bot branding and more advanced analytics — not needed now.
- The bot is separate from Carl-bot (joins) and The Arbiter (subscriptions). Each does one job. Don't conflate them.
- All ticket transcripts in `#ticket-logs` are staff-only. Members get a DM copy when their ticket closes (if that setting is enabled).
---
**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️
**Created by:** Chronicler #45
**Date:** March 28, 2026
**Status:** Ready to implement