599 lines
14 KiB
Markdown
599 lines
14 KiB
Markdown
# Gmail-Discord-Zammad Bridge - New Features Documentation
|
|
|
|
This document outlines all the features implemented in the latest update.
|
|
|
|
---
|
|
|
|
## Phase 1: Foundation & Core Commands
|
|
|
|
### 1. Variables System
|
|
A powerful template system for dynamic messages using placeholders.
|
|
|
|
**Available Variables:**
|
|
- `{ticket.user}` / `{ticket.creator}` - Ticket creator username
|
|
- `{ticket.email}` - Customer email address
|
|
- `{ticket.number}` - Ticket number
|
|
- `{ticket.subject}` - Ticket subject line
|
|
- `{ticket.claimed}` - "Yes" or "No"
|
|
- `{ticket.claimedby}` - Staff member name or "Unclaimed"
|
|
- `{ticket.priority}` - Ticket priority level
|
|
- `{staff.user}` - Staff username
|
|
- `{staff.name}` - Staff display name
|
|
- `{staff.mention}` - Staff mention (@user)
|
|
- `{server.name}` - Discord server name
|
|
- `{server.membercount}` - Server member count
|
|
- `{hours}` - Hours (for auto-messages)
|
|
- `{date}` - Current date
|
|
- `{time}` - Current time
|
|
|
|
**Usage:** Variables work in tags, welcome messages, and other customizable messages.
|
|
|
|
---
|
|
|
|
### 2. Tags/Saved Responses System
|
|
Create, manage, and use saved responses for common questions.
|
|
|
|
**Commands:**
|
|
- `/tag send <name>` - Send a saved response
|
|
- `/tag create <name> <content>` - Create new tag
|
|
- `/tag edit <name> <content>` - Edit existing tag
|
|
- `/tag delete <name>` - Delete a tag
|
|
- `/tag list` - List all available tags
|
|
- `/tag set <tag>` - Set ticket category tag (dropdown: Server Down, Billing, Mod Help, etc.); renames channel (priority emoji first, then tag emoji)
|
|
|
|
**Features:**
|
|
- Autocomplete support for tag names
|
|
- Usage counter tracking
|
|
- Supports variable substitution
|
|
- Database-backed persistence
|
|
|
|
**Database Table:**
|
|
```sql
|
|
CREATE TABLE tags (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
name TEXT UNIQUE NOT NULL,
|
|
content TEXT NOT NULL,
|
|
created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000),
|
|
created_by TEXT,
|
|
use_count INTEGER DEFAULT 0
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
### 3. User Management Commands
|
|
|
|
#### `/add @user`
|
|
Add a user to the current ticket thread.
|
|
|
|
**Permissions:** Sets ViewChannel, SendMessages, and ReadMessageHistory for the user.
|
|
|
|
#### `/remove @user`
|
|
Remove a user from the current ticket thread.
|
|
|
|
**Behavior:** Deletes the permission overwrite for the user.
|
|
|
|
---
|
|
|
|
### 4. `/help` Command
|
|
Displays a comprehensive embed with all available commands, organized by category.
|
|
|
|
**Categories:**
|
|
- User Management
|
|
- Ticket Management
|
|
- Tags (Saved Responses)
|
|
- Variables
|
|
- Panel System
|
|
- Other
|
|
|
|
---
|
|
|
|
## Phase 2: Ticket Management
|
|
|
|
### 1. `/transfer @staff [reason]`
|
|
Transfer a ticket to another staff member.
|
|
|
|
**Features:**
|
|
- Validates target has staff role
|
|
- Updates claimed_by in database
|
|
- Logs to logging channel
|
|
- Optional reason parameter
|
|
|
|
---
|
|
|
|
### 2. `/move #category`
|
|
Move a ticket to a different category.
|
|
|
|
**Features:**
|
|
- Preserves permissions (lockPermissions: true)
|
|
- Logs the move
|
|
- Works with any category channel
|
|
|
|
---
|
|
|
|
### 3. `/force-close`
|
|
Force close a ticket without confirmation.
|
|
|
|
**Features:**
|
|
- Generates transcript
|
|
- Updates Zammad (if configured)
|
|
- Archives channel after 5 seconds
|
|
- No confirmation required
|
|
|
|
---
|
|
|
|
### 4. Close Confirmation System
|
|
When clicking the "Close Ticket" button, users now see a confirmation prompt.
|
|
|
|
**Flow:**
|
|
1. User clicks "Close Ticket"
|
|
2. Confirmation buttons appear (ephemeral)
|
|
3. User clicks "Confirm Close" or "Cancel"
|
|
4. If confirmed, ticket closes as usual
|
|
|
|
**Database Table:**
|
|
```sql
|
|
CREATE TABLE close_requests (
|
|
ticket_id TEXT PRIMARY KEY,
|
|
requested_by TEXT NOT NULL,
|
|
reason TEXT,
|
|
created_at INTEGER NOT NULL,
|
|
FOREIGN KEY (ticket_id) REFERENCES tickets(gmail_thread_id)
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
### 5. `/topic <text>`
|
|
Set the channel topic/description for a ticket.
|
|
|
|
**Use Cases:**
|
|
- Document ticket status
|
|
- Add important notes
|
|
- Set expectations
|
|
|
|
---
|
|
|
|
## Phase 3: UX Enhancements
|
|
|
|
### 1. Enhanced Claiming System
|
|
|
|
#### Claim Overwrite
|
|
**Config:** `ALLOW_CLAIM_OVERWRITE=true/false`
|
|
|
|
When enabled, allows staff to claim tickets already claimed by someone else.
|
|
|
|
**Behavior:**
|
|
- If disabled: Shows error message when trying to claim someone else's ticket
|
|
- If enabled: Allows claim overwrite, updates claimed_by
|
|
|
|
#### Auto-Unclaim on Inactivity
|
|
**Config:**
|
|
- `AUTO_UNCLAIM_ENABLED=true/false`
|
|
- `AUTO_UNCLAIM_AFTER_HOURS=24`
|
|
|
|
Automatically unclaims tickets after specified hours of inactivity.
|
|
|
|
**Features:**
|
|
- Checks every hour
|
|
- Based on last_activity timestamp
|
|
- Sends notification message in channel
|
|
- Resets claimed_by to NULL
|
|
|
|
#### Claim Timeout
|
|
**Config:**
|
|
- `CLAIM_TIMEOUT_ENABLED=true/false`
|
|
- `CLAIM_TIMEOUT_HOURS=48`
|
|
|
|
Set a maximum time for claims (future enhancement placeholder).
|
|
|
|
---
|
|
|
|
### 2. Modal Forms for Ticket Creation
|
|
Users can create Discord-side tickets through an interactive modal form.
|
|
|
|
**Form Fields:**
|
|
- Subject (required, short text, max 100 chars)
|
|
- Description (required, paragraph, max 1000 chars)
|
|
- Priority (optional, low/normal/high)
|
|
|
|
**Workflow:**
|
|
1. User clicks "Open Ticket" button on panel
|
|
2. Modal appears with form fields
|
|
3. User fills out and submits
|
|
4. Bot creates ticket channel automatically
|
|
|
|
**Features:**
|
|
- Validates priority input
|
|
- Auto-generates ticket numbers
|
|
- Sets proper permissions
|
|
- Sends welcome message
|
|
- Logs creation
|
|
|
|
---
|
|
|
|
### 3. Priority System
|
|
|
|
#### `/priority <level>`
|
|
Set ticket priority via dropdown: **low**, **normal**, **medium**, or **high** (default: normal).
|
|
|
|
**Features:**
|
|
- Dropdown choices: 🟢 Low, 🟡 Normal, 🟠 Medium, 🔴 High
|
|
- When priority is set, the channel/thread name is prefixed with the priority emoji
|
|
- Color-coded embeds
|
|
- Database-backed
|
|
- Visible in ticket embeds
|
|
|
|
**Priority Colors:**
|
|
- High: Red (#FF0000)
|
|
- Normal / Medium: Info color
|
|
- Low: Green (#00FF00)
|
|
|
|
**Configuration:**
|
|
```env
|
|
PRIORITY_ENABLED=true
|
|
DEFAULT_PRIORITY=normal
|
|
PRIORITY_HIGH_EMOJI=🔴
|
|
PRIORITY_MEDIUM_EMOJI=🟡
|
|
PRIORITY_LOW_EMOJI=🟢
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 4: Panel & Category System
|
|
|
|
### 1. Panel System
|
|
|
|
#### `/panel #channel [title] [description]`
|
|
Create a ticket panel that users can interact with to open tickets.
|
|
|
|
**Features:**
|
|
- Customizable title and description
|
|
- "Open Ticket" button
|
|
- Sends modal form on click
|
|
- Creates Discord-only tickets
|
|
|
|
**Example Panel:**
|
|
```
|
|
Title: Open a Support Ticket
|
|
Description: Click the button below to create a new support ticket.
|
|
A staff member will assist you shortly.
|
|
[🎫 Open Ticket]
|
|
```
|
|
|
|
---
|
|
|
|
### 2. Discord-Side Tickets
|
|
Tickets created through panels are Discord-only (no email integration).
|
|
|
|
**Features:**
|
|
- Stored in same tickets table
|
|
- gmail_thread_id uses format: `discord-{timestamp}-{userId}`
|
|
- sender_email contains Discord tag
|
|
- Full feature parity with email tickets
|
|
|
|
---
|
|
|
|
### 3. Category System
|
|
The bot now supports multiple categories through the `/move` command.
|
|
|
|
**Features:**
|
|
- Move tickets between categories
|
|
- Preserves permissions
|
|
- Works with both email and Discord tickets
|
|
|
|
---
|
|
|
|
### 4. Thread-Style Tickets
|
|
**Config:**
|
|
- `USE_THREADS=true/false`
|
|
- `THREAD_PARENT_CHANNEL=<channel_id>`
|
|
|
|
When enabled, creates tickets as threads instead of channels.
|
|
|
|
**Benefits:**
|
|
- Cleaner server structure
|
|
- No channel limit concerns
|
|
- Better organization
|
|
|
|
**Note:** Implementation ready for future activation.
|
|
|
|
---
|
|
|
|
## Phase 5: Automation (Future Enhancement)
|
|
|
|
### Automation Rules Engine
|
|
A framework for creating custom automation rules.
|
|
|
|
**Planned Features:**
|
|
- Trigger-based actions
|
|
- Condition matching
|
|
- Custom workflows
|
|
- Schedule support
|
|
|
|
**Example Rules:**
|
|
- Auto-assign based on keywords
|
|
- Auto-tag based on content
|
|
- Auto-escalate high priority
|
|
- Auto-move based on game/topic
|
|
|
|
**Note:** Foundation in place, specific rules to be implemented based on needs.
|
|
|
|
---
|
|
|
|
## Database Schema Updates
|
|
|
|
### Tickets Table
|
|
```sql
|
|
CREATE TABLE IF NOT EXISTS tickets (
|
|
gmail_thread_id TEXT PRIMARY KEY,
|
|
discord_thread_id TEXT,
|
|
sender_email TEXT,
|
|
subject TEXT,
|
|
created_at INTEGER,
|
|
status TEXT DEFAULT 'open',
|
|
transcript_message_id TEXT,
|
|
claimed_by TEXT,
|
|
escalated INTEGER DEFAULT 0,
|
|
ticket_number INTEGER,
|
|
rename_count INTEGER DEFAULT 0,
|
|
rename_window_start INTEGER DEFAULT 0,
|
|
zammad_ticket_id INTEGER,
|
|
priority TEXT DEFAULT 'normal',
|
|
last_activity INTEGER,
|
|
reminder_sent INTEGER DEFAULT 0
|
|
);
|
|
```
|
|
|
|
### Tags Table
|
|
```sql
|
|
CREATE TABLE IF NOT EXISTS tags (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
name TEXT UNIQUE NOT NULL,
|
|
content TEXT NOT NULL,
|
|
created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000),
|
|
created_by TEXT,
|
|
use_count INTEGER DEFAULT 0
|
|
);
|
|
```
|
|
|
|
### Close Requests Table
|
|
```sql
|
|
CREATE TABLE IF NOT EXISTS close_requests (
|
|
ticket_id TEXT PRIMARY KEY,
|
|
requested_by TEXT NOT NULL,
|
|
reason TEXT,
|
|
created_at INTEGER NOT NULL,
|
|
FOREIGN KEY (ticket_id) REFERENCES tickets(gmail_thread_id)
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration Reference
|
|
|
|
### New Environment Variables
|
|
|
|
```env
|
|
# --- CLAIMING OPTIONS ---
|
|
CLAIM_TIMEOUT_ENABLED=false
|
|
CLAIM_TIMEOUT_HOURS=48
|
|
AUTO_UNCLAIM_ENABLED=false
|
|
AUTO_UNCLAIM_AFTER_HOURS=24
|
|
ALLOW_CLAIM_OVERWRITE=false
|
|
|
|
# --- THREAD-STYLE TICKETS ---
|
|
USE_THREADS=false
|
|
THREAD_PARENT_CHANNEL=
|
|
```
|
|
|
|
---
|
|
|
|
## Complete Command Reference
|
|
|
|
### User Management
|
|
- `/add @user` - Add user to ticket
|
|
- `/remove @user` - Remove user from ticket
|
|
|
|
### Ticket Management
|
|
- `/transfer @staff [reason]` - Transfer ticket to another staff member
|
|
- `/move #category` - Move ticket to another category
|
|
- `/force-close` - Force close without confirmation
|
|
- `/topic <text>` - Set channel topic
|
|
- `/priority <level>` - Set ticket priority (low/normal/medium/high); renames channel with priority emoji
|
|
- `/escalate [reason] [tier]` - Escalate ticket to tier 2 or 3
|
|
- `/deescalate` - De-escalate ticket
|
|
|
|
### Tags System
|
|
- `/tag send <name>` - Send saved response
|
|
- `/tag create <name> <content>` - Create new tag
|
|
- `/tag edit <name> <content>` - Edit existing tag
|
|
- `/tag delete <name>` - Delete tag
|
|
- `/tag list` - List all tags
|
|
|
|
### Panel System
|
|
- `/panel #channel [title] [description]` - Create ticket panel
|
|
|
|
### Help
|
|
- `/help` - Show all commands
|
|
|
|
---
|
|
|
|
## Migration Notes
|
|
|
|
### From Previous Version
|
|
|
|
1. **Database Migration**: New columns added automatically on startup
|
|
- priority
|
|
- last_activity
|
|
- reminder_sent
|
|
|
|
2. **New Tables**: Created automatically
|
|
- tags
|
|
- close_requests
|
|
|
|
3. **Environment Variables**: Add to `.env`:
|
|
```env
|
|
CLAIM_TIMEOUT_ENABLED=false
|
|
AUTO_UNCLAIM_ENABLED=false
|
|
ALLOW_CLAIM_OVERWRITE=false
|
|
USE_THREADS=false
|
|
```
|
|
|
|
4. **No Breaking Changes**: All existing functionality preserved
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
### Tags
|
|
- Use descriptive names (e.g., `welcome`, `closing`, `escalation-info`)
|
|
- Include variables for personalization
|
|
- Keep content concise but helpful
|
|
- Review and update regularly
|
|
|
|
### Priority System
|
|
- Set priority early in ticket lifecycle
|
|
- Use high priority sparingly
|
|
- Review priority regularly
|
|
- Consider SLA based on priority
|
|
|
|
### Panels
|
|
- Place in dedicated support channels
|
|
- Use clear, welcoming language
|
|
- Include instructions
|
|
- Monitor for spam/abuse
|
|
|
|
### Claiming
|
|
- Enable auto-unclaim to prevent stale claims
|
|
- Set reasonable timeout periods
|
|
- Use overwrite cautiously
|
|
- Communicate with team about transfers
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Commands Not Appearing
|
|
- Verify `DISCORD_APPLICATION_ID` is set
|
|
- Check bot has application.commands scope
|
|
- Wait up to 1 hour for Discord to sync
|
|
- Restart bot after .env changes
|
|
|
|
### Modal Not Showing
|
|
- Ensure user has Create Posts permission
|
|
- Check for Discord outages
|
|
- Verify bot has proper permissions
|
|
|
|
### Tags Not Working
|
|
- Check database file permissions
|
|
- Verify SQLite is installed
|
|
- Check for SQL syntax errors in content
|
|
- Use `/tag list` to confirm tag exists
|
|
|
|
### Priority Not Updating
|
|
- Verify ticket exists in database
|
|
- Check PRIORITY_ENABLED is true
|
|
- Ensure valid priority value (low/normal/high)
|
|
|
|
---
|
|
|
|
## Performance Considerations
|
|
|
|
### Database
|
|
- SQLite suitable for small-medium deployments
|
|
- Consider MongoDB migration for high volume
|
|
- Regular backups recommended
|
|
- Vacuum database periodically
|
|
|
|
### Auto-Checks
|
|
- Auto-close: Runs every hour
|
|
- Auto-unclaim: Runs every hour
|
|
- Reminders: Runs every 30 minutes
|
|
- Adjust intervals in code if needed
|
|
|
|
### Rate Limits
|
|
- Channel creation: 50/day per guild
|
|
- Channel rename: 2 per 10 minutes per channel ([Discord docs](https://discord.com/developers/docs/topics/rate-limits)). When the limit is reached, the bot skips the rename and posts: *Channel renamed too quickly. Try again \<t:unlock:R\>.*
|
|
- Message edits: Be cautious with bulk operations
|
|
|
|
---
|
|
|
|
## Future Enhancements
|
|
|
|
### Planned Features
|
|
1. **Statistics Dashboard**: Track ticket metrics
|
|
2. **Feedback System**: Collect user ratings
|
|
3. **Advanced Automations**: Rule builder UI
|
|
4. **Ticket Templates**: Pre-filled forms
|
|
5. **SLA Tracking**: Response time monitoring
|
|
6. **Multi-language**: Localization support
|
|
7. **Web Dashboard**: View tickets in browser
|
|
8. **API Endpoints**: External integrations
|
|
|
|
### Community Requests
|
|
- Custom ticket categories per game
|
|
- User blacklist system
|
|
- Scheduled availability hours
|
|
- Ticket assignment rotation
|
|
- Knowledge base integration
|
|
|
|
---
|
|
|
|
## Support & Contributing
|
|
|
|
### Getting Help
|
|
- Check documentation first
|
|
- Review troubleshooting section
|
|
- Check logs for error messages
|
|
- Test with minimal configuration
|
|
|
|
### Reporting Bugs
|
|
Include:
|
|
- Steps to reproduce
|
|
- Expected behavior
|
|
- Actual behavior
|
|
- Environment details
|
|
- Log excerpts
|
|
|
|
### Feature Requests
|
|
Consider:
|
|
- Use case description
|
|
- Priority/importance
|
|
- Potential workarounds
|
|
- Similar existing features
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
### v2.0.0 - Major Feature Update
|
|
**Added:**
|
|
- Variables system for dynamic messages
|
|
- Tags/saved responses system
|
|
- User management commands (/add, /remove)
|
|
- Transfer, move, force-close commands
|
|
- Close confirmation flow
|
|
- Enhanced claiming (overwrite, auto-unclaim)
|
|
- Modal forms for ticket creation
|
|
- Priority system
|
|
- Panel system for Discord tickets
|
|
- Thread-style tickets option
|
|
- Comprehensive /help command
|
|
|
|
**Improved:**
|
|
- Database schema with new fields
|
|
- Permission handling
|
|
- Error messages
|
|
- Logging
|
|
|
|
**Fixed:**
|
|
- Various edge cases
|
|
- Permission issues
|
|
- Database constraints
|
|
|
|
---
|
|
|
|
*Last Updated: 2025*
|
|
*Version: 2.0.0*
|