Home › Requirements & Install

Requirements & Install

Install Staff Chat in a few minutes.

Requirements

WHMCS 8.x or 9.x.
PHP as required by your WHMCS version, with curl and fileinfo enabled.
OpenSSL support for the WHMCS encrypt()/decrypt() helpers.
A writable modules/addons/StaffChat/data directory.
HTTPS for service-worker desktop notifications.
A running WHMCS daily cron.

Before you install

Back up your WHMCS database and the existing modules/addons/StaffChat folder, if any.
Confirm the WHMCS daily cron is configured and running.
Decide which administrator roles should see the widget.

Install

Upload the StaffChat folder to modules/addons/.
Go to Configuration → System Settings → Addon Modules and activate Staff Chat.
Open Access Control and tick the roles that may use the widget.
In Administrator Roles & Permissions, make sure those roles also hold the Addon Modules permission.
Click Configure and review the module settings.
Open the Staff Chat dashboard and confirm the widget appears in the admin footer.

Full Administrator pages — the dashboard, settings, chat history and activity log pages are restricted to the Full Administrator role even when another role has widget access.

Access control

There are two independent gates:

Addon Modules → Access Control decides which roles see the widget.
Administrator Roles & Permissions needs the Addon Modules permission for the same role.

If a role has the widget but not the permission, the widget is not rendered. If the role has the permission but is not selected in Access Control, the module pages are still refused.

Data directory

On first run the module creates data/ with an Apache deny rule and stores encrypted history, attachments, presence, typing and preview caches there. The web server user must be able to write to it.

modules/addons/StaffChat/data/
  history.json
  attachments.json
  unread.json
  presence.json
  typing.json
  previews.json
  uploads/*.enc

Never serve data/ directly — keep the bundled deny rule in place. If you use Nginx, add an equivalent location block that denies /modules/addons/StaffChat/data/.

Nginx

location ^~ /modules/addons/StaffChat/data/ {
    deny all;
    return 403;
}

IIS — place this web.config inside modules/addons/StaffChat/data/:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <security>
      <authorization>
        <remove users="*" roles="" verbs="" />
        <add accessType="Deny" users="*" />
      </authorization>
    </security>
  </system.webServer>
</configuration>

Upgrading

Back up the data/ directory first.
Replace the module files; the settings and activity-log tables are created or updated automatically.
Legacy plaintext attachments are encrypted on upgrade, on the daily cron, or on first download.
Existing settings, chat history and attachment metadata are preserved.

Deactivation

If Delete Chat History is ticked in Addon Modules, deactivation removes the encrypted history, attachments and unread counters. Leave it unticked to keep the data for a later reactivation.

Post-install checklist

The widget appears and expands.
Two admins can exchange a message in Group Chat.
Private chat opens from the online list.
@mentions highlight the mentioned admin.
An image uploads, previews and opens in the lightbox.
Chat History lists the message and CSV export downloads.
The Activity Log records the connect event.