BREAKING CHANGE: Major refactor to support multiple helpdesk platforms ✨ Features: - Add automatic platform detection (FreeScout/Help Scout) - Implement platform-specific adapters for seamless integration - Support both React/SPA (Help Scout) and traditional DOM (FreeScout) - Add GPT-5 and GPT-5 Mini model support - Enhance security with comprehensive HTML sanitization 🏗️ Architecture: - Introduce adapter pattern with platformAdapter base class - Add platform detection with 5-minute caching - Create dedicated adapters for FreeScout and Help Scout - Extract HTML sanitization to shared utility module 🔧 Improvements: - Add debounced operations for better performance - Enhance error handling and debugging capabilities - Update manifest for broader URL permissions - Improve context extraction for both platforms 📝 Documentation: - Update README with multi-platform capabilities - Add CHANGELOG for version tracking - Document platform-specific features and integration 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
21 KiB
GPT Assistant for FreeScout & Help Scout
A powerful Chrome extension that integrates OpenAI's GPT models with both FreeScout and Help Scout platforms to generate intelligent, context-aware customer support responses. Features advanced documentation integration, customer data extraction, tone matching, and automatic platform detection for seamless multi-platform support.
🚀 Features
Core AI Integration
- Multiple Model Support: GPT-5, GPT-5 Mini, GPT-4o Mini, GPT-4o, GPT-4 Turbo, and GPT-3.5 Turbo
- Smart Context Building: Automatically extracts conversation history and customer information
- Tone Matching: Analyzes your previous responses to maintain consistent communication style
- Customizable System Prompts: Define your support agent's personality and guidelines
Documentation Integration
- llms.txt Support: Automatically fetch and include relevant documentation in AI responses
- Smart Caching: 24-hour cache with manual refresh capability
- Cache Management: Visual cache status indicators and manual clearing
- Multiple Sources: Support for any documentation URL following llms.txt format
Customer Intelligence (WordPress Integration)
When used with the WordPressFreeScout module, the extension automatically extracts and includes:
- Customer Profile: Name, registration date, CRM system
- Product Information: Current plugin version with update recommendations
- License Details: Status, expiration dates, active sites count
- Purchase History: Recent orders, amounts, and payment methods
- Technical Context: Active integrations, CRM tags, site URLs
- Support Context: Last license check, version status warnings
Advanced Configuration
- Temperature Control: Adjust response creativity (0.1 = consistent, 0.9 = creative)
- Token Limits: Control response length and API costs (50-4000 tokens)
- Custom Shortcuts: Configurable keyboard shortcuts (default: Ctrl+Shift+G)
- Model Selection: Choose the best OpenAI model for your needs
- Feedback System: Optional response quality tracking (can be disabled)
- Error Handling: Detailed error messages for troubleshooting
Multi-Platform Support
- Automatic Platform Detection: Works seamlessly with both FreeScout and Help Scout
- FreeScout Features: Full WordPress integration, Summernote editor support
- Help Scout Features: React/SPA support, dynamic content handling, appData integration
- Security: Comprehensive HTML sanitization and XSS prevention
- Performance: 5-minute detection caching, debounced operations
User Experience
- Visual Feedback: "🤖 Generating AI response..." status indicator
- Optional Context Input: Type context/notes in the reply field before generation
- Response Feedback System: Rate responses and track improvement over time
- Markdown Support: Automatic conversion of links and bold text
- Editor Integration: Native support for both platforms' WYSIWYG editors
- Personalized Signatures: Automatic sign-offs using agent names
📦 Installation
-
Download the Extension
- Clone this repository or download as ZIP
- Extract to a local folder
-
Load in Chrome
- Open Chrome and navigate to
chrome://extensions/
- Enable "Developer mode" (top right toggle)
- Click "Load unpacked" and select the extension folder
- Open Chrome and navigate to
-
Get OpenAI API Key
- Visit OpenAI API Keys
- Create a new API key
- Copy the key for configuration
⚙️ Configuration
Basic Setup
- Click the extension icon in your Chrome toolbar
- Configure required settings:
- OpenAI API Key: Your API key from OpenAI
- OpenAI Model: Choose GPT-4o (recommended), GPT-4 Turbo, or GPT-3.5 Turbo
- System Prompt: Customize the AI's behavior and tone
- Keyboard Shortcut: Default is Ctrl+Shift+G (Cmd+Shift+G on Mac)
Advanced Settings
-
Temperature: Control response creativity
0.1
= Very consistent, predictable responses0.7
= Balanced (default)0.9
= More creative, varied responses
-
Max Tokens: Control response length (50-4000)
500
= Short responses1000
= Medium responses (default)2000+
= Longer, detailed responses
-
Enable Feedback System: Toggle response quality tracking
Checked
= Show thumbs up/down buttons after responses (default)Unchecked
= Disable feedback collection for cleaner interface
💰 Cost Estimation
Based on OpenAI's current pricing (as of 2025) and assuming an average conversation thread of 6 messages with customer data and documentation:
Typical Usage Scenario
- Input: ~2,000 tokens (conversation history + customer data + documentation)
- Output: ~300 tokens (generated response)
- Total per response: ~2,300 tokens
Cost per Response by Model
Model | Input Cost | Output Cost | Total Cost per Response |
---|---|---|---|
GPT-4o | $0.0025 per 1K tokens | $0.01 per 1K tokens | ~$0.008 |
GPT-4 Turbo | $0.01 per 1K tokens | $0.03 per 1K tokens | ~$0.029 |
GPT-3.5 Turbo | $0.0005 per 1K tokens | $0.0015 per 1K tokens | ~$0.001 |
Monthly Cost Examples
Light Usage (50 responses/month):
- GPT-4o: ~$0.40/month
- GPT-4 Turbo: ~$1.45/month
- GPT-3.5 Turbo: ~$0.05/month
Medium Usage (200 responses/month):
- GPT-4o: ~$1.60/month
- GPT-4 Turbo: ~$5.80/month
- GPT-3.5 Turbo: ~$0.20/month
Heavy Usage (500 responses/month):
- GPT-4o: ~$4.00/month
- GPT-4 Turbo: ~$14.50/month
- GPT-3.5 Turbo: ~$0.50/month
Cost Optimization Tips
-
Choose the Right Model:
- GPT-4o: Best balance of quality and cost (recommended)
- GPT-4 Turbo: Highest quality, highest cost
- GPT-3.5 Turbo: Most economical, good for simple responses
-
Optimize Token Usage:
- Set appropriate max_tokens limits (500-1000 for most responses)
- Use concise system prompts
- Keep documentation focused and relevant
-
Monitor Usage:
- Check your OpenAI usage dashboard regularly
- Set up billing alerts in your OpenAI account
- Track response quality vs. cost for your use case
-
Leverage Prompt Caching (Automatic):
- The extension automatically implements OpenAI's Prompt Caching
- Reduces latency by up to 80% and costs by up to 75%
- No configuration needed - works automatically with GPT-4o and newer models
- See "Prompt Caching" section below for details
Note: Prices are subject to change. Check OpenAI's pricing page for current rates.
Documentation Integration
-
Prepare Documentation
- Create an
llms.txt
file with your documentation - Host it on a publicly accessible URL
- Format: llms.txt specification
- Create an
-
Configure Docs URL
- Add your documentation URL in the extension settings
- The extension will automatically cache and include relevant docs
Example llms.txt format:
# Product Setup Guide
URL: https://example.com/setup
Step-by-step instructions for setting up the product...
# Troubleshooting Common Issues
URL: https://example.com/troubleshooting
Solutions for frequently encountered problems...
🔌 WordPress Integration
This extension works seamlessly with the WordPressFreeScout module by Very Good Plugins to provide enhanced customer intelligence.
What the WordPress Module Provides
The WordPressFreeScout module displays customer information in FreeScout's sidebar, which this extension automatically extracts and includes in AI responses:
- Customer Profile Data
- EDD (Easy Digital Downloads) Order History
- Software License Information
- Active Plugin Integrations
- CRM Tags and Segmentation
- Version Status and Update Recommendations
Installation Requirements
-
Install WordPressFreeScout Module
- Follow instructions at verygoodplugins/WordPressFreeScout
- Configure the WordPress connection in FreeScout
-
Verify Integration
- Ensure customer data appears in FreeScout's conversation sidebar
- The extension will automatically detect and extract this information
Supported Data Extraction
The extension intelligently parses the WordPress widget to extract:
<!-- Customer Basic Info -->
- Customer Name: Kyle Newton
- Registered: 04/18/2022
- Active CRM: Groundhogg (This Site)
- Current Version: 3.41.41 (with update warnings)
<!-- License Information -->
- License Status: Active
- Expires: 04/18/2026
- Active Sites: 150+ sites
- Sample Sites: my.tribepub.com, wellhealthcenters.com, etc.
<!-- Purchase History -->
- Recent Orders: Renewals, amounts, dates
- Product: WP Fusion — Professional
- Payment Method: Stripe
<!-- Technical Context -->
- Active Integrations: EDD, WooCommerce, Gravity Forms, etc.
- CRM Tags: Customer segments and status
🎯 Usage
Generating Responses
- Open a FreeScout conversation
- Optional: Add context - Type any context or notes in the reply field (e.g., "this was a bug and we fixed it for today's 3.43.3 update")
- Press your configured shortcut (default: Ctrl+Shift+G)
- Wait for generation - you'll see "🤖 Generating AI response..."
- Review and edit the generated response as needed
- Send the response using FreeScout's normal send button
Using Optional Context
You can provide additional context to help the AI generate more accurate responses:
Example workflow:
- Type in reply field: "this was a bug and we fixed it for today's 3.43.3 update"
- Press Ctrl+Shift+G
- AI generates: "Hi John, thanks for reporting this issue. This was indeed a bug that we've addressed in today's 3.43.3 update. Please update to the latest version and the issue should be resolved. Let me know if you need any help with the update process. Best, Sarah"
Common context examples:
- "offer 20% discount for renewal"
- "this feature will be available in next month's release"
- "customer is on legacy plan, needs migration"
- "escalate to development team"
Providing Feedback on AI Responses
After each AI response is generated, you'll see feedback buttons:
Rate the response:
- 👍 Good - Response was helpful and accurate
- 👎 Needs Work - Response needs improvement
For negative feedback:
- Provide specific notes about what could be improved
- Common feedback areas: tone, accuracy, length, context usage
Feedback Analytics:
- View success rates and improvement trends in extension settings
- Get personalized suggestions based on your feedback patterns
- Export detailed feedback reports for analysis
📊 Response Feedback System
The extension includes an intelligent feedback system to help you track and improve AI response quality over time.
How It Works
After each AI response generation:
- Feedback buttons appear below the reply editor (👍 Good / 👎 Needs Work)
- Rate the response with a single click
- Add improvement notes (optional) for negative feedback
- Data is stored locally in your browser for privacy
Feedback Analytics Dashboard
Available in extension settings:
- Success Rate: Percentage of positive vs negative responses (last 30 days)
- Response Volume: Total number of rated responses
- Smart Suggestions: AI-powered recommendations based on feedback patterns
- Trend Analysis: Track improvement over time
Common Feedback Patterns
The system automatically identifies issues and provides suggestions:
Issue Detected | Suggested Improvement |
---|---|
Too formal/robotic | Add "Use a friendly, conversational tone" to system prompt |
Too casual | Add "Maintain a professional tone" to system prompt |
Missing context | Provide more specific context before generation |
Too long/verbose | Reduce max tokens or add "Be concise" to system prompt |
Too short/incomplete | Increase max tokens or add "Provide detailed explanations" |
Wrong tone | Review tone instructions and previous message analysis |
Data Management
Granular cleanup options in settings:
- Clear 30+ days old - Remove outdated feedback entries
- Clear 90+ days old - More aggressive cleanup for storage management
- Clear negative only - Focus on positive patterns only
- Clear all feedback - Complete reset of feedback data
Export and Analysis:
- View All Feedback Data - Opens comprehensive HTML report
- Individual entry details - Response text, notes, customer context, timestamps
- Bulk statistics - Success rates, common issues, improvement trends
Privacy and Storage
- Local storage only - All feedback data stays in your browser
- No external servers - Complete privacy and control
- Automatic cleanup - Configurable retention periods
- Export capability - Take your data with you anytime
Best Practices
For optimal feedback insights:
- Rate consistently - Try to rate most responses for accurate trends
- Be specific in notes - Detailed feedback generates better suggestions
- Regular cleanup - Remove old data monthly to keep insights current
- Act on suggestions - Update system prompts based on recommendations
- Monitor trends - Check analytics weekly to track improvement
Feedback categories to consider:
- Accuracy: Was the information correct?
- Tone: Did it match your communication style?
- Completeness: Did it address all customer concerns?
- Context usage: Did it incorporate provided context well?
- Professional quality: Would you send this response as-is?
Disabling Feedback
If you prefer a cleaner interface:
- Open extension settings
- Uncheck "Enable response feedback system"
- Save settings
The feedback system is enabled by default but can be completely disabled if you find it intrusive. All existing feedback data is preserved when disabled and will reappear if you re-enable the feature.
Best Practices
System Prompt Tips:
The extension comes with a default system prompt that you can edit.
Here is the default system prompt:
You are a helpful customer support agent for [Company Name]. Please provide clear, concise, and friendly responses to customer inquiries.
Guidelines:
- Be authoritative yet approachable in your tone
- Keep responses concise but complete
- Always reference relevant documentation links when applicable
- Use a helpful, professional tone
- If you mention documentation, include the specific URL
- Structure your response clearly with bullet points or numbered lists when helpful
- Do not make use of markdown headings
- You can make tasteful use of emojis
- End with an offer to help further if needed
When referencing documentation, format links as: [Link Text](URL)
Documentation Organization:
- Keep sections focused and specific
- Include URLs for each section
- Update regularly to maintain accuracy
- Test with common customer scenarios
Customer Context Usage:
- The extension automatically includes customer data in prompts
- AI responses will be personalized with customer names
- Version warnings and license status are automatically considered
- Purchase history provides context for renewal discussions
🛠️ Advanced Features
Tone Matching
The extension analyzes your previous responses in conversations to maintain consistency:
- Extracts your communication style from past messages
- Matches formality level and language patterns
- Maintains your personal support voice across conversations
Error Handling
Comprehensive error reporting helps with troubleshooting:
- API key validation before requests
- Detailed OpenAI API error messages
- Network and configuration issue detection
- Helpful suggestions for common problems
Cache Management
Smart caching reduces API calls and improves performance:
- 24-hour cache for documentation
- Visual cache status indicators
- Manual cache clearing capability
- Automatic cache busting for fresh content
Prompt Caching (OpenAI Feature)
The extension automatically implements OpenAI's Prompt Caching to dramatically improve performance and reduce costs:
Automatic Benefits:
- Up to 80% faster response times - Cached prompts are processed much faster
- Up to 75% cost reduction - Cached tokens cost significantly less
- No configuration needed - Works automatically with compatible models
- No additional fees - Prompt caching is free from OpenAI
How It Works:
- Static content (system prompt, documentation) is placed first for optimal caching
- Dynamic content (conversation, customer info) is placed last
- A unique cache key routes similar requests to the same servers
- Cache remains active for 5-10 minutes (up to 1 hour during off-peak)
Monitoring Performance: Check the browser console for cache metrics:
GPT Assistant: Prompt caching active! 1920 tokens cached (78.3% hit rate, ~58.7% cost savings)
Requirements:
- Prompts must exceed 1024 tokens for caching to activate
- Works with GPT-4o and newer models
- Best results with consistent system prompts and documentation
Optimization Tips:
- Keep your system prompt and documentation URL consistent
- Make frequent requests to maintain cache warmth
- Longer, detailed documentation improves cache hit rates
- Monitor console logs to verify caching is working
🔧 Troubleshooting
Common Issues
"No OpenAI API key configured"
- Ensure you've entered your API key in settings
- Check for extra spaces or formatting issues
"API Error (401): Invalid API key"
- Verify your OpenAI API key is correct
- Check that your OpenAI account has sufficient credits
"API Error (429): Rate limit exceeded"
- You've exceeded OpenAI's rate limits
- Wait a few minutes or upgrade your OpenAI plan
No customer data appearing
- Ensure WordPressFreeScout module is installed and configured
- Verify customer data appears in FreeScout's sidebar
- Check browser console for JavaScript errors
Debug Information
Enable Chrome DevTools Console to see detailed logs:
- Press F12 in FreeScout or Help Scout
- Go to Console tab
- Trigger the extension and review any error messages
Useful debugging commands in console:
// Check if extension loaded
console.log(window.gptAssistant);
// Check detected platform
window.gptAssistant.platformManager.getPlatform()
// Should return: 'freescout' or 'helpscout'
// Check health status
await window.gptAssistant.getHealth()
// Should show: {status: 'healthy', ...}
// View performance metrics
window.gptAssistant.getMetrics()
📋 Requirements
- Chrome Browser: Version 88+ (Manifest V3 support)
- FreeScout: Any recent version
- OpenAI Account: With API access and credits
- WordPressFreeScout Module: Optional, for enhanced customer data
🤝 Contributing
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
Development Setup
- Clone the repository
- Make your changes
- Test thoroughly in a FreeScout environment
- Submit a pull request with detailed description
📄 License
This project is open source. Please check the license file for details.
🙏 Acknowledgments
- Very Good Plugins for the WordPressFreeScout module
- OpenAI for providing the GPT API
- FreeScout for the excellent help desk platform
📝 Changelog
Version 2.0.1 (Latest)
- ✅ NEW: Help Scout Support - Full compatibility with Help Scout platform
- ✅ NEW: Prompt Caching - Automatic OpenAI prompt caching for 80% faster responses and 75% cost reduction
- ✅ FIXED: Duplicate Response Bug - Fixed issue where responses were inserted twice in Help Scout
- ✅ IMPROVED: Documentation Parsing - Better handling of large documentation files
- Enhanced error handling and debugging capabilities
- Added comprehensive debug console commands
Version 2.0.0
- Major rewrite for multi-platform support
- Added Help Scout platform detection and integration
- Improved React/SPA compatibility
- Enhanced Slate.js editor support
Version 1.1
- ✅ NEW: Optional Context Input - Type context/notes in the reply field before generating AI responses
- ✅ NEW: Response Feedback System - Rate AI responses with thumbs up/down and provide improvement notes
- The AI will incorporate your context into the generated response
- Perfect for providing specific information like "this was fixed in today's update" or "offer 20% discount"
- Context text gets replaced with the full AI-generated response
- Feedback analytics help identify patterns and suggest improvements
Version 1.0
- Initial release with GPT-4 integration for FreeScout
- WordPress customer data extraction
- Documentation integration with llms.txt support
- Tone matching and personalized signatures
- Smart caching and error handling
📞 Support
For issues with this extension:
- Open an issue on GitHub
- Include browser console errors
- Describe your FreeScout and WordPress setup
For issues with the WordPressFreeScout module:
- Visit verygoodplugins/WordPressFreeScout
- Follow their support guidelines
Made with ❤️ for the FreeScout community