Staff Chatfor WHMCS · Documentation
v2.0.0
Home › Admin Usage Guide

Admin Usage Guide

How the widget and chat controls work.

Opening the widget

The widget floats above the admin footer on every page. Click the header to expand or collapse it. When collapsed, the launcher shows a badge for unread messages. The initial state is controlled by Chat box on first load in Settings.

Rooms

  • Group Chat — shared by every approved admin.
  • Chat with — click an online admin in the right-hand list to open a private 1:1 room.
  • The active room is highlighted and its unread badge clears when you open it.
  • Private rooms are only available when Private chat is enabled.

Sending messages

  • Type in the composer and press Enter to send, or click the send button.
  • Messages are limited by Maximum message length.
  • URLs are detected and made clickable; they open in a new tab.
  • Replies are visible to everyone in the room within one polling interval.

Mentions

  • Type @ to open the autocomplete list, or click the @ button.
  • Selecting an admin inserts @[Admin Name].
  • Mentions are highlighted for everyone; when you are mentioned the highlight is stronger and the browser title is marked.
  • Ghost-mode admins are mentioned by their masked display name.

Emoji and reactions

  • Click the emoji button to open the picker and insert an emoji into the composer.
  • Hover a message and choose a reaction: 👍 ❤️ 😂 🎉 😮 😢.
  • Click the same reaction again to remove it.
  • Counts update live and are also shown in Chat History and CSV exports.

Editing and deleting

  • Hover your own message to reveal Edit. Editing is allowed only inside the configured window (Edit window, default 5 minutes).
  • An edited message is marked as edited.
  • Full Administrators can delete any message; the action asks for confirmation with SweetAlert2.
  • Deleting a message also removes its attachment and the attachment metadata.

Typing indicator

When another admin is composing, the room header shows their name and “is typing…”. The indicator expires automatically and can be disabled in Settings.

Attachments

  • Click the paperclip and choose one file or image.
  • Images render inline; click an image to open the full-size lightbox.
  • Other files appear as a download chip with a size label.
  • Uploads are checked against the MIME allowlist and the configured size limit.
  • Attachments are encrypted at rest and downloaded through an authenticated endpoint.

Link previews

When a message contains a URL, the module fetches a small text-only preview (title and description) server-side. Previews are cached for a day, never follow redirects and reject private or reserved addresses. They can be switched off in Settings.

  • Open Staff Chat → Chat History from the admin navigation.
  • Use the room selector to narrow to Group Chat or a private room.
  • The search field covers all rooms, admin names, message text and attachment names.
  • Results are newest first and can be sorted and paged.
  • Attachment previews and downloads are available directly from the results.
  • Use Export CSV to download the current view.

Dashboard analytics

The module Dashboard turns the stored history into operational charts. All values are aggregated server-side from the encrypted stores.

  • Messages per day — the last 30 days, newest day on the right.
  • Activity by hour — message volume for each hour of the day, so peak staffing times are obvious.
  • Room distribution — the split between Group Chat and private 1:1 rooms.
  • Top mentioned admins — ranked by how many @[Admin Name] mentions they received.
  • Attachment overview — file count, encrypted disk usage and a breakdown by Images, PDFs, ZIPs, Text and Other.

Refresh requests a new aggregate from the module's analytics endpoint. The result is cached for one minute and the cache invalidates automatically when history or attachments change.

Notifications

  • Mute or unmute sound from the widget header or the Notifications panel.
  • Enable desktop notifications per widget, then use Send test notification to confirm.
  • The panel reports the browser permission, service-worker state and the Chrome/OS setting.
  • Chrome also needs to be allowed in the operating system notification settings.

Read-only access

Admins in a read-only role can read the room, open attachments and react, but the composer and attachment button are disabled. The server rejects sends from read-only roles even if the client is bypassed.

Ghost mode

A ghost-mode admin can chat normally but does not appear in the online list, and their messages show as Hidden admin. Full Administrators can still identify the sender in Chat History.