Client Onboarding Pro for WHMCS

Documented release: 1.2.1
Licence product slug: client-onboarding-pro
Installation directory: modules/addons/client_onboarding_pro

1. Overview

Client Onboarding Pro adds a multi-step onboarding wizard to WHMCS. Administrators can create questions, collect customer answers, score responses, assign segments, monitor completion and execute configured automations.

The module can create an onboarding session when a client registers or signs in. Depending on configuration, it can display a resume banner, redirect the customer, or block most client-area pages until onboarding is completed.

2. Compatibility and requirements

• WHMCS 8.10 or 9.x
• PHP 8.1–8.3
• MySQL 5.7+ or MariaDB 10.3+
• PHP cURL, OpenSSL and fileinfo extensions
• HTTPS-enabled WHMCS installation
• Correct WHMCS System URL
• Working WHMCS daily cron
• Write access to the configured upload/report locations when those features are used
• Active AngleModules licence

The packaged customer interface uses Alpine.js and the administration analytics use Chart.js. Test content-security-policy and theme compatibility before production rollout.

3. Before installation

1. Back up WHMCS files and database.
2. Create a staging WHMCS customer who is not an administrator.
3. Keep Force Required disabled during initial testing.
4. Decide what customer data is genuinely necessary; do not collect sensitive information without a lawful reason and retention policy.
5. Prepare your privacy notice and staff access rules.

4. Installation

1. Extract the release.

2. Upload client_onboarding_pro to:

   /path/to/whmcs/modules/addons/client_onboarding_pro/

3. Open WHMCS Admin → System Settings → Addon Modules.

4. Activate Client Onboarding Pro.

5. Grant access only to appropriate administrator roles.

6. Enter the AngleModules licence key in addon settings.

7. Open the addon and confirm that the licence is Active.

Activation creates the mod_cop_* database tables and seeds example questions and default segments.

5. Licence activation

The customer enters only the licence key. The endpoint, product identity and RSA public key are embedded.

1. Enter the licence key in Addon Modules → Client Onboarding Pro.
2. Save the configuration.
3. Open Addons → Client Onboarding Pro → Licence.
4. Select refresh if the newly saved status is not visible.
5. Verify the domain, product and offline-grace information.

Use a licence issued for client-onboarding-pro. Never distribute the private signing key.

6. Core addon settings

Redirect modes

• First login: begins onboarding when an eligible client first signs in.
• Every login until complete: continues redirecting until the session is completed.
• Manual: the customer opens the onboarding page manually; Force Required overrides this behavior.

Force Required warning

Force Required can block access to services, invoices and tickets until onboarding finishes. Authentication, registration, logout, password reset, verification, cart, checkout, knowledgebase and announcement routes are exempted by the module.

Do not enable Force Required until:

• At least one active question exists.
• A normal customer can complete every step.
• File-upload questions work with server limits.
• The onboarding page works in the production WHMCS theme.
• You have an emergency method to disable the addon setting.

7. Question builder

Supported question types include:

• Radio
• Checkbox
• Dropdown
• Text
• Textarea
• Multi-select
• File upload
• Rating
• Date
• Number

Per-question options can include:

• Title and description
• Answer choices
• Step number and label
• Required/optional status
• Active/inactive status
• Sort order
• Validation rules
• Conditional display logic
• Branching data
• Lead-score weight
• Per-answer score mapping

After changing question order or step numbers, test an existing in-progress session and a new session. Existing sessions can retain progress based on the earlier structure.

8. Steps and customer experience

Questions are grouped by their step number. The customer wizard:

1. Loads the authenticated customer’s onboarding session.
2. Loads active questions for the relevant steps.
3. Saves or submits answers through authenticated API actions.
4. Updates progress and lead score.
5. Marks the session completed after the final step.
6. Assigns a segment when automatic segmentation is enabled.
7. Runs applicable completion automations.

Customers can resume an incomplete session. Whether they can skip depends on Force Required and the customer interface configuration.

9. Lead scoring and segments

Lead score can come from a base question weight and an answer-specific score mapping. When onboarding completes, the module can assign an active segment whose score range contains the final score.

Avoid overlapping segment ranges. Use an unbroken structure such as:

Segment scores are prioritization signals, not proof of creditworthiness, fraud risk or purchasing intent.

10. Sessions and client records

The administration interface can filter sessions by:

• Status
• Segment
• Minimum score
• Customer name
• Email
• Company

The session detail page shows submitted answers and recent analytics/timeline events. Access should be limited to staff who need customer onboarding data.

Typical states include not started, in progress, completed, skipped and abandoned.

11. Automation rules

Rules contain:

• Rule name
• Trigger event
• Optional conditions
• Action type
• Action configuration
• Priority
• Active/inactive state

Available triggers include onboarding completion, abandonment, score thresholds, segment assignment, step completion and answer submission.

Implemented action types include:

• Send a WHMCS email template
• Assign a manager value
• Set a segment
• Send an HTTP webhook
• Create a WHMCS support ticket
• Add a WHMCS client note
• Write an administrator notification to the activity log
• Record an upsell opportunity in the activity log

Automation testing

Create one test rule at a time. Confirm its event, conditions and side effect before adding another rule. A badly configured completion rule can send duplicate or incorrect customer communication.

For email actions, use a valid WHMCS email template name. For tickets, use a valid department ID. For webhook actions, use HTTPS and verify the signature at the receiving endpoint.

12. Webhooks

Webhook delivery uses an HTTP POST containing JSON. When a secret is configured, payloads are signed using HMAC-SHA256.

Receiving applications should:

1. Require HTTPS.
2. Verify the signature using the exact raw request body.
3. Reject old/replayed events when timestamp/event information permits.
4. Return a successful HTTP status only after accepting the event.
5. Store no more customer data than necessary.

Do not send onboarding answers to third-party systems until your privacy notice and data-processing arrangements cover that transfer.

13. Abandoned-session processing

During the WHMCS daily cron, an in-progress session whose updated_at value is older than the configured threshold is marked abandoned. The automation engine then processes applicable abandoned-session rules and scheduled-report definitions.

This is daily processing, not exact-time scheduling. A seven-day threshold can be applied after seven days plus the delay until the next successful cron.

If an abandoned customer signs in again, the module can return the session to in-progress status.

14. Reports and exports

Available data sets include:

• Session/completion data
• Abandoned sessions
• Lead-score rankings
• Segment distribution
• Raw answers

Important export limitations

• CSV: real CSV download.
• Excel: XML Spreadsheet content downloaded as .xls; it is not native .xlsx content.
• PDF: printable HTML output; it is not a generated PDF binary in release 1.2.1.
• Scheduled report generation is basic and must be tested before relying on email delivery or archival.

Do not advertise “native XLSX” or “PDF export” until the exporter uses a real XLSX/PDF library and the output has been tested.

15. Dashboard and analytics

The dashboard summarizes onboarding sessions, completion, abandonment, lead score, recent activity and segment distribution. Analytics are operational indicators based on module records; they are not a complete revenue-attribution system.

16. File uploads

The API enforces configured size limits and validates allowed extensions/MIME information. Also verify PHP and web-server limits:

• upload_max_filesize
• post_max_size
• Request-body limits in the web server/proxy
• Writable upload directory

Uploaded onboarding documents may contain personal or confidential data. Protect the storage location from direct public listing and define a deletion schedule.

17. Upgrade

1. Back up files and database.
2. Disable Force Required temporarily.
3. Upload the new client_onboarding_pro directory over the existing directory.
4. Keep existing mod_cop_* tables.
5. Open the addon to allow database migrations.
6. Confirm the module version and licence status.
7. Test login, redirects, answer submission, completion and automation with a non-admin customer.
8. Re-enable Force Required only after verification.

18. Deactivation and data removal

Deactivation retains onboarding data and the signed licence cache. It does not intentionally erase the module tables.

If permanent removal is required, first export required records and back up the database. Deleting mod_cop_* tables is irreversible and should be a deliberate administrator operation.

19. Security and privacy

• Limit addon access by administrator role.
• Use HTTPS for WHMCS, webhooks and licensing.
• Use a long random webhook secret and rotate it if exposed.
• Keep API rate limiting enabled.
• Never collect passwords, card details, government IDs or secrets through ordinary onboarding questions.
• Review file uploads and customer answers under your privacy/retention policy.
• Keep WHMCS and PHP patched.
• Test CSRF enforcement after upgrades.

20. Common problems

Redirect loop

Disable Force Required in addon settings, confirm active questions exist, clear the WHMCS template cache and test the onboarding route directly.

Customer is not redirected

Check Enable Onboarding, redirect mode, session status, active questions, hook loading, licence state and theme output.

Onboarding page is blank or unstyled

Check browser developer-console errors, external script restrictions, CSP rules, template overrides and asset URLs.

Automation did not run

Confirm the rule is active, the trigger matches the recorded event, conditions match exact stored values and required action configuration is valid. For abandonment, confirm the WHMCS daily cron ran.

Email action failed

Verify the WHMCS email template name and customer ID. Inspect the WHMCS activity and email logs.

Webhook failed

Test DNS/TLS connectivity from the WHMCS server, endpoint response status, timeout, payload signature and receiving-server logs.

Licence page shows invalid

Confirm the licence is active for client-onboarding-pro, the WHMCS hostname is authorized and outbound HTTPS is available.

21. Known limitations

• The included PDF export is printable HTML, not a true PDF file.
• The Excel export is XML Spreadsheet content, not native XLSX.
• Chart/customer UI dependencies may be affected by restrictive CSP or unavailable external assets.
• Force Required depends partly on client-area hooks and browser redirection; custom themes/routes require testing.
• Saved-filter and scheduled-report interfaces are basic in this release.
• Analytics are based on module events, not full marketing attribution.
• Configuration is installation-wide rather than separately defined per WHMCS client group.

22. Support checklist

• Module, WHMCS and PHP versions
• Redirect mode and Force Required setting
• Customer ID and session ID
• Question/step involved
• Trigger, conditions and action for automation issues
• Redacted browser console and WHMCS logs
• Cron execution time for abandonment/report issues
• Confirmation that the problem occurs with a non-admin customer