Skip to content

jaanmeld/CustomerCorrection

BranchesTags

Repository files navigation

CustomerCorrection Module for FreeScout

Automatically corrects conversations where support agents incorrectly appear as customers. This typically happens when agents send emails to customers, and the system misidentifies the agent as the customer.

Features

  • ✅ Automatically detects and corrects misidentified agent/customer roles
  • ✅ Web-based Admin Interface - Configure via FreeScout admin panel (no file editing needed)
  • ✅ Manual Execution - "Fix Now" button with real-time preview and results
  • ✅ Scheduled task automation (daily, weekly, or monthly)
  • ✅ Optional real-time correction on conversation creation
  • ✅ Dry-run mode for testing before applying changes
  • ✅ Comprehensive logging and debugging
  • ✅ Configurable agent email addresses and mailboxes via web UI
  • ✅ Skips agent-to-agent internal communications

Installation

Step 1: Deploy Module to Docker Container

Copy the entire CustomerCorrection folder to your FreeScout Docker container:

# Via docker cp
docker cp Modules/CustomerCorrection/ <container_name>:/www/html/Modules/

# Or via Portainer file manager
# Upload the CustomerCorrection folder to /www/html/Modules/

Step 2: Configure Module

Option A: Web Interface (Recommended)

  1. Log in to FreeScout as an administrator
  2. Navigate to: /customer-correction/settings in your browser
    • Example: https://your-freescout.com/customer-correction/settings
  3. Configure settings via the web interface:
    • Add agent email addresses (one per line)
    • Select mailboxes to monitor
    • Set schedule frequency and automation options
    • Click "Save Settings"

Option B: Configuration File (Alternative)

Access your Docker container via Portainer console and edit the configuration:

cd /www/html/Modules/CustomerCorrection/Config
nano config.php

Update the following settings:

'agent_emails' => [
    'support@yourcompany.com',  // Replace with your agent emails
    'help@yourcompany.com',
    'sales@yourcompany.com',
],

'mailbox_ids' => [2, 3],  // Replace with your mailbox IDs (or [] for all)

'schedule_frequency' => 'weekly',  // Options: daily, weekly, monthly

'process_days' => 30,  // Process conversations from last 30 days

Note: Settings configured via the web interface take priority over the config file.

Step 3: Enable Module

In the Docker container at /www/html/:

cd /www/html

# Enable the module
php artisan module:enable CustomerCorrection

# Clear caches
php artisan clear-compiled
php artisan config:clear
php artisan route:clear

Step 4: Verify Installation

# Check if module is enabled
php artisan module:list

# Verify command is available
php artisan list | grep fix-agent-customer-swap

# Check scheduled tasks
php artisan schedule:list

# Test with dry-run
php artisan freescout:fix-agent-customer-swap --mailbox-id=2 --agent-emails="support@company.com" --dry-run=1 --debug=1

Configuration Options

Edit Config/config.php to customize module behavior:

agent_emails (array, required)

List of agent email addresses to detect and correct:

'agent_emails' => [
    'support@yourcompany.com',
    'help@yourcompany.com',
],

mailbox_ids (array)

Mailbox IDs to monitor. Leave empty [] to process all mailboxes:

'mailbox_ids' => [2, 3],  // Specific mailboxes
// OR
'mailbox_ids' => [],      // All mailboxes

schedule_frequency (string)

How often to run automatic corrections:

  • 'daily' - Runs every day at 2:00 AM
  • 'weekly' - Runs every Sunday at 2:00 AM
  • 'monthly' - Runs on the 1st of each month at 2:00 AM
'schedule_frequency' => 'weekly',

auto_fix_on_create (boolean)

Enable real-time correction when conversations are created:

'auto_fix_on_create' => false,  // Recommended: false

⚠️ Warning: Real-time correction may impact performance on high-volume systems. Test thoroughly before enabling in production.

debug_enabled (boolean)

Enable detailed logging:

'debug_enabled' => false,  // Set to true for troubleshooting

process_days (integer|null)

Process conversations created within last X days:

'process_days' => 30,  // Last 30 days
// OR
'process_days' => null,  // All conversations

Usage

Web Interface (Recommended Method)

Access the admin interface at: /customer-correction/settings

Step-by-Step Usage:

  1. Access Settings Page

    • Log in to FreeScout as administrator
    • Navigate to: https://your-freescout.com/customer-correction/settings
    • You'll see the Customer Correction settings page

  2. Configure Agent Emails

    • In the "Agent Email Addresses" field, enter agent emails (one per line)
    • Example: 
      support@yourcompany.com
help@yourcompany.com
sales@yourcompany.com
    • These are the emails that will be detected and corrected when they appear as customers

  3. Select Mailboxes to Monitor

    • Choose which mailboxes to process from the dropdown
    • Hold Ctrl/Cmd to select multiple mailboxes
    • Leave all unselected to process all mailboxes

  4. Configure Automation

    • Schedule Frequency: Choose how often to run automatically
      • Daily (every day at 2:00 AM)
      • Weekly (every Sunday at 2:00 AM)
      • Monthly (1st of each month at 2:00 AM)
    • Process Last X Days: Set how many days back to check (e.g., 30)
    • Real-time Correction: Enable to auto-fix on conversation creation (⚠️ test first)

  5. Advanced Options

    • Debug Mode: Enable for detailed troubleshooting logs
    • Logs saved to: storage/logs/customer-correction.log

  6. Save Settings

    • Click "Save Settings" button
    • Settings are stored in database (higher priority than config file)

  7. Manual Execution

    • Scroll down to "Manual Execution" section
    • Select mailbox and date range
    • Click "Preview (Dry Run)" to see what would change
    • Click "Fix Now" to apply corrections
    • View real-time output in the browser

Web Interface Features:

  • ✅ Settings Management - Configure all options via web form
  • ✅ Manual Execution - Run corrections on-demand with instant feedback
  • ✅ Preview Mode - Dry-run to see changes before applying
  • ✅ Real-time Results - Command output shown directly in browser
  • ✅ Flexible Filtering - Choose specific mailboxes and date ranges
  • ✅ No File Editing - All configuration via database

Automatic Execution (Scheduled Task)

The module automatically runs based on your schedule_frequency configuration. Ensure FreeScout's Laravel scheduler is running:

# Check if scheduler is active
php artisan schedule:list

# Manually trigger scheduler (for testing)
php artisan schedule:run

Manual Execution via Command Line

Run the command manually as needed:

# Dry run (preview changes)
php artisan freescout:fix-agent-customer-swap \
  --mailbox-id=2 \
  --agent-emails="support@company.com,help@company.com" \
  --dry-run=1 \
  --debug=1

# Execute corrections
php artisan freescout:fix-agent-customer-swap \
  --mailbox-id=2 \
  --agent-emails="support@company.com" \
  --force=1

# Process recent conversations only
php artisan freescout:fix-agent-customer-swap \
  --mailbox-id=2 \
  --agent-emails="support@company.com" \
  --days=7 \
  --force=1

# Fix specific conversation
php artisan freescout:fix-agent-customer-swap \
  --conversation-id=500 \
  --agent-emails="support@company.com" \
  --force=1

Command Options

  • --mailbox-id= - ID of the mailbox to process
  • --conversation-id= - Fix specific conversation ID
  • --days= - Process conversations created within last X days
  • --agent-emails= (required) - Comma-separated list of agent emails
  • --debug=0 - Enable debug mode (default: 0)
  • --dry-run=0 - Preview changes without applying (default: 0)
  • --force=0 - Required flag to actually update conversations (default: 0)

How It Works

  1. Scans Conversations: Identifies conversations where the "customer" email matches a configured agent email
  2. Examines First Thread: Looks at the original email's "To" field to find the actual customer
  3. Swaps Roles:
    • Updates conversation customer_email to the real customer
    • Changes source_via from CUSTOMER to USER (agent-initiated)
    • Updates thread type from TYPE_CUSTOMER to TYPE_MESSAGE
  4. Skips Internal Communications: Agent-to-agent conversations are left unchanged
  5. Reports Statistics: Provides detailed counts of swapped, skipped, and already-correct conversations

Module Management

Enable/Disable Module

# Enable
php artisan module:enable CustomerCorrection

# Disable
php artisan module:disable CustomerCorrection

# Check status
php artisan module:list

Update Configuration

After editing Config/config.php:

php artisan config:clear
php artisan clear-compiled

View Logs

Scheduled task output is logged to:

/www/html/storage/logs/customer-correction.log

View logs:

tail -f /www/html/storage/logs/customer-correction.log

Troubleshooting

Module Not Loading

# Verify module location
ls -la /www/html/Modules/CustomerCorrection/

# Check module.json
cat /www/html/Modules/CustomerCorrection/module.json

# Enable module
php artisan module:enable CustomerCorrection

# Clear caches
php artisan clear-compiled
php artisan config:clear

Command Not Found

# Verify command file exists
ls -la /www/html/Modules/CustomerCorrection/Console/

# List available commands
php artisan list | grep customer

# Check service provider
cat /www/html/Modules/CustomerCorrection/Providers/CustomerCorrectionServiceProvider.php

Scheduled Task Not Running

# Check Laravel scheduler
php artisan schedule:list

# Verify FreeScout cron is active
ps aux | grep schedule:run

# Manually test command
php artisan freescout:fix-agent-customer-swap --dry-run=1 --debug=1

No Conversations Being Corrected

  1. Verify agent emails are configured correctly in Config/config.php
  2. Check that conversations exist with agents as customers
  3. Run with --debug=1 to see detailed processing
  4. Ensure --force=1 flag is used (not --dry-run=1)

Safety Features

  • Dry-Run Mode: Preview all changes before applying
  • Force Flag Required: Prevents accidental data modification
  • Preserves Timestamps: Original conversation dates are maintained
  • Skips Internal Communications: Agent-to-agent emails are left unchanged
  • Detailed Logging: Debug mode provides comprehensive operation logs
  • Error Handling: Failed corrections are logged and skipped

Example Output

Processing conversations for mailbox: Support (support@company.com)
Filtering to conversations created within last 30 days
Found 150 conversations to check

✅ Processing completed!
📊 Statistics:
   - Total conversations checked: 150
   - Matching agent emails: 25
     • Customer/Agent swapped: 20
     • Already correct: 3
     • Skipped (errors): 2
   - Non-agent conversations (skipped): 125

Requirements

  • FreeScout >= 1.8.0
  • Laravel Scheduler must be running
  • PHP 7.4+
  • Write access to storage/logs directory

Support

For issues or questions:

  1. Check module logs: storage/logs/customer-correction.log
  2. Run with --debug=1 flag for detailed output
  3. Review FreeScout documentation: https://github.com/freescout-help-desk/freescout/wiki

License

This module is provided as-is for FreeScout installations. Use at your own risk.

Version

Version: 1.0.0

Roadmap

Future Enhancements

v1.1.0 - Settings Integration (Planned)

  • Move to Settings Sidebar: Integrate with FreeScout's main settings menu
    • Appear alongside "General", "Mail Settings", "Alerts", "User Fields"
    • Route change: /customer-correction/settings → /settings/customer-correction
    • Use settings.sections Eventy filter for menu registration
    • Adopt FreeScout's settings layout pattern
    • Benefits: Better UX, consistent navigation, easier discovery

v1.2.0 - Enhanced Features (Planned)

  • Bulk Operations: Process multiple mailboxes with progress tracking
  • Notifications: Email alerts for scheduled task results
  • Statistics Dashboard: Visual charts of corrections over time
  • Undo Functionality: Revert corrections if needed
  • Advanced Filtering: Filter by date range, customer domain, conversation tags

v1.3.0 - Performance Improvements (Planned)

  • Queue Integration: Process large batches via Laravel queue system
  • Incremental Processing: Resume interrupted operations
  • Caching: Cache agent email lookups for faster processing
  • Background Jobs: Non-blocking manual execution for large datasets

Contributing

Suggestions and contributions welcome! To propose features:

  1. Open an issue describing the enhancement
  2. Include use cases and expected behavior
  3. Reference version number for roadmap placement

Changelog

v1.0.0 (2025-10-06)

  • ✅ Initial release
  • ✅ Web-based admin interface
  • ✅ Manual execution with dry-run mode
  • ✅ Scheduled task automation (daily/weekly/monthly)
  • ✅ Database-driven configuration
  • ✅ Real-time AJAX execution with output display
  • ✅ Comprehensive logging and debugging
  • ✅ Command-line interface with multiple options

About

Freescout module that sets correct costumer in cases when initiator is Freescout account.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages