Staff Chatfor WHMCS · Documentation
v2.0.0
Home › Troubleshooting

Troubleshooting

Fast fixes for common issues.

The widget is missing

  • Check the master Staff Chat widget switch in Settings.
  • Check Addon Modules → Access Control for the admin's role.
  • The role also needs the Addon Modules permission in Administrator Roles & Permissions.
  • Confirm the module is activated, not just uploaded.
  • Clear the WHMCS template cache if the footer still looks stale.

Chat shows 403 or 404

  • Directly opening a chat endpoint is intentionally rejected; this is not an error.
  • A 403 usually means the CSRF token expired or the admin session changed. Reload the admin page and try again.
  • A 404 from the widget can mean the role lost module access. Recheck Access Control and the role permission.
  • If the whole admin area returns 500, check the PHP error log and debug.log in the module folder.

Desktop notifications do not appear

  • Open widget Settings → Notifications and click Send test notification.
  • Allow notifications for the site in the browser.
  • Chrome: enable Google Chrome in the Windows or macOS notification settings.
  • Turn off Focus Assist or Do Not Disturb.
  • HTTPS is required for the service worker; plain HTTP falls back to in-page notifications only.
  • If a service worker is stuck, unregister it in the browser developer tools and reload.

Upload rejected

  • Only JPG, PNG, GIF, WebP, PDF, TXT and ZIP are allowed.
  • Check the configured attachment size limit.
  • Check PHP upload_max_filesize and post_max_size; the lower of the two wins.
  • Make sure data/uploads/ exists and is writable.
  • A failed MIME check rejects the file even if the extension looks correct.

Attachment unavailable

  • Check that data/uploads/ is writable and not empty.
  • Confirm the attachment was not deleted with its message.
  • Downloads require a valid admin session and CSRF token; reload the page and retry.
  • If files were copied without data/, the metadata exists but the bytes do not.
  • Search covers all rooms, admins, message text and attachment names.
  • Clear the date or room filter if one is active.
  • Ghost-mode admins are searchable as “Hidden admin”, not by their real name.
  • In live-only mode there is no stored history to search.

History is empty

  • Confirm Live-only mode is off.
  • Check the retention period; 90 days is the default.
  • Confirm data/history.json exists and is readable by PHP.
  • If the encryption key changed, old history cannot be decrypted. Restore the previous WHMCS configuration.

Messages arrive slowly

  • Lower the Polling interval; 5 seconds is the default.
  • Check server load and any admin-area caching or CDN rules.
  • Make sure the admin session is not timing out between polls.

Retention is not running

  • Confirm the WHMCS daily cron is configured and running.
  • Retention also runs when the Activity Log or Chat History page is opened.
  • Check file permissions if pruning cannot rewrite the JSON files.

Settings will not save

  • A validation error is shown next to the field; correct it and save again.
  • Reload the page if the CSRF token expired.
  • Confirm the database user can write to hsc_staffchat_settings.

Diagnostics

Enable WHMCS module debug logging if you need more detail, reproduce the issue, then check modules/addons/StaffChat/debug.log. Remove or rotate the log afterwards; do not include it in a release package.