From 54d615e7f048115af9ab27cf424aba32dc61b8ba Mon Sep 17 00:00:00 2001 From: "Claude (Chronicler #45)" Date: Sat, 28 Mar 2026 21:05:50 +0000 Subject: [PATCH] docs: add comprehensive Ticket Tool setup guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/guides/ticket-tool-setup-guide.md | 411 +++++++++++++++++++++++++ 1 file changed, 411 insertions(+) create mode 100644 docs/guides/ticket-tool-setup-guide.md diff --git a/docs/guides/ticket-tool-setup-guide.md b/docs/guides/ticket-tool-setup-guide.md new file mode 100644 index 0000000..bb6bb3a --- /dev/null +++ b/docs/guides/ticket-tool-setup-guide.md @@ -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