CustomerSync Module for FreeScout

CustomerSync is an integration module for FreeScout helpdesk that allows external systems (such as WHMCS, WordPress, client portals, or custom PHP websites) to securely synchronize customer details and authenticate visitors via signed payloads.

Background: CustomerSync was created to simplify customer support workflows by automatically linking website visitors to their account profiles across WHMCS, WordPress, or custom portals.

Important GDPR & Privacy Notice: Linking and synchronizing user account data across systems requires explicit user consent under GDPR and data privacy laws. As a website operator, you are solely responsible for obtaining explicit consent from your users on your website BEFORE triggering the synchronization payload. The CustomerSync module functions purely as a technical data transmission interface and does not manage user consent.

Features

• HMAC-SHA256 Signed Payloads: Cryptographically secure customer data transmission using shared secret keys.
• Seamless Single Sign-On (SSO): Automatically authenticates visitors and links chat sessions or support tickets to their existing customer profiles.
• Flexible Field Mapping: Map external payload fields (name, email, phone, custom fields) directly to FreeScout customer attributes.
• CORS & Domain Protection: Restrict API synchronization requests to authorized external website domains.
• Expiration Protection: Anti-replay timestamp verification for secure payload handling.

Installation

1. Download or clone this repository into the Modules/CustomerSync directory of your FreeScout installation.
2. Navigate to Manage -> Modules in your FreeScout admin panel.
3. Activate the CustomerSync module.
4. Configure your integration settings under Manage -> Settings -> CustomerSync.

Integration Example (PHP)

$secret = 'YOUR_SHARED_SECRET_KEY';
$payloadData = [
    'email' => 'user@example.com',
    'name' => 'John Doe',
    'phone' => '+1234567890',
    'timestamp' => time()
];

$jsonPayload = base64_encode(json_encode($payloadData));
$signature = hash_hmac('sha256', $jsonPayload, $secret);

Requirements

• FreeScout helpdesk v1.18.0 or higher
• PHP 8.1 or higher (PHP 8.x)

License

Licensed under the GNU General Public License v3.0 (GPLv3).