A FreeScout module that displays customer subscription information from Qonversion directly in the FreeScout conversation sidebar, allowing support agents to view customer subscription details without leaving the help desk interface.
- Subscription Status - View active, expired, or non-existent subscriptions at a glance
- Platform Detection - See which platform (iOS/Android) the customer uses
- Direct Links - One-click access to customer profiles in Qonversion dashboard
- Real-Time Data - Always shows current subscription status from Qonversion
- Mailbox Selection - Choose which mailboxes display the Qonversion sidebar
- Clean UI - Seamlessly integrated sidebar design matching FreeScout's aesthetic
- FreeScout: Version 1.8.0 or higher
- PHP: 7.4 or higher (8.0+ recommended)
- Qonversion Account: With API access enabled
- Server: Outbound HTTPS access to api.qonversion.io
Clone the module into your FreeScout modules directory:
cd /var/www/html/Modules
sudo git clone https://github.com/YOUR-USERNAME/freescout-qonversion-integration.git QonversionIntegrationSet proper permissions:
sudo chown -R www-data:www-data QonversionIntegration
sudo chmod -R 755 QonversionIntegrationNote: Replace www-data with your web server user if different (e.g., apache, nginx)
Clear FreeScout cache:
cd /var/www/html
sudo php artisan cache:clear
sudo php artisan config:clear- Activate the module in FreeScout via Manage → Modules
- Configure module settings via Manage → Settings → Qonversion
Once configured, the module automatically displays subscription information in the conversation sidebar for customers in the selected mailboxes.
This module uses the customer's email address from FreeScout to query Qonversion's API. It requires that your app uses email addresses as Identity UIDs in Qonversion (which is a common setup).
- Extract customer email from FreeScout conversation
- Query Qonversion Identity API:
GET /v3/identities/{email} - If found, fetch entitlements:
GET /v3/users/{user_id}/entitlements - Parse subscription status and display in sidebar
Check module is installed:
cd /var/www/html
php artisan module:listYou should see QonversionIntegration in the list.
Clear cache:
sudo php artisan cache:clear
sudo php artisan config:clear- Verify module is activated in Manage → Modules
- Verify API credentials are configured in Manage → Settings → Qonversion
- Check that both Project Key and Project ID are filled in
- Check that the mailbox is selected in settings (or leave all unchecked to show in all mailboxes)
- Open a conversation and refresh the page
Possible causes:
- Wrong Project Key - Verify your Project Key in Qonversion dashboard
- Email Mismatch - Ensure your app sends email as Identity UID to Qonversion
- Wrong Environment - Check if you're using Production vs Sandbox
- No Subscriptions - Customer may genuinely have no subscription history
Debug by checking logs:
sudo tail -f /var/www/html/storage/logs/laravel.log | grep -i qonversionCheck server can reach Qonversion:
curl -I https://api.qonversion.io/v3/Should return HTTP/1.1 401 Unauthorized (which is expected without credentials).
Check firewall allows outbound HTTPS:
- Ensure port 443 outbound is open
- Whitelist api.qonversion.io if using firewall rules
cd /var/www/html/Modules
sudo chown -R www-data:www-data QonversionIntegration
sudo chmod -R 755 QonversionIntegration# View all logs
sudo tail -100 /var/www/html/storage/logs/laravel.log
# Watch logs in real-time
sudo tail -f /var/www/html/storage/logs/laravel.log
# Search for Qonversion-specific errors
sudo grep "Qonversion" /var/www/html/storage/logs/laravel.logModify Public/css/module.css to customize colors, spacing, or fonts.
Edit Resources/views/sidebar.blade.php to show/hide fields or change formatting.
After any changes, clear cache:
sudo php artisan cache:clear- Real-Time Fetching: Data is fetched fresh from Qonversion on each conversation view for accuracy.
- Lazy Loading: Data is only fetched when viewing a conversation, not on list pages.
- Error Handling: Failed API calls are logged but don't break the sidebar display.
- Low Volume Optimized: Ideal for support teams with moderate conversation volume.
- ✅ API key stored securely in FreeScout database
- ✅ API key masked in settings form
- ✅ All API requests use HTTPS
- ✅ No customer data stored locally
- ✅ Logs scrubbed of sensitive data
cd /var/www/html/Modules/QonversionIntegration
sudo git pull origin main
sudo php artisan cache:clear
sudo php artisan config:clear- Download latest release
- Backup your current installation
- Replace files (keep your config if needed)
- Clear cache
- Go to Manage → Modules
- Click Deactivate next to QonversionIntegration
cd /var/www/html/Modules
sudo rm -rf QonversionIntegration
cd /var/www/html
sudo php artisan cache:clear
sudo php artisan config:clearModule settings will remain in database but won't be used.
Contributions are welcome! Here's how you can help:
- 🐛 Report Bugs - Open an issue with details
- 💡 Suggest Features - Open an issue with your idea
- 🔧 Submit PRs - Fork, branch, code, test, and submit
git clone https://github.com/YOUR-USERNAME/freescout-qonversion-integration.git
cd freescout-qonversion-integration
# Make your changes
# Test thoroughly
git commit -m "Description of changes"
git push origin your-feature-branch- Follow PSR-12 coding standards
- Comment complex logic
- Test with FreeScout 1.8+ and PHP 8.0+
- Update README if adding features
Q: Does this work with Stripe subscriptions managed by Qonversion?
A: Yes! The module works with any subscription source tracked by Qonversion (iOS, Android, Web/Stripe).
Q: What if a customer has multiple email addresses?
A: The module uses the primary email address from the FreeScout conversation.
Q: Can I see historical subscription data?
A: The sidebar shows current status. Click "View in Qonversion" for full history.
Q: Does this slow down FreeScout? A: Minimally. API calls only happen when viewing conversations and have a 10-second timeout.
Q: Can non-admin users see subscription data?
A: Yes. All users with access to conversations can see the sidebar data.
Q: What data does this module send to Qonversion?
A: Only the customer's email address for lookup purposes.
This module is open-source software licensed under the MIT License.