How to Configure the Client Notifications Extension
Go to Addons > Phox WHMCS Templates > Extensions, find Client Notifications and click Manage. The extension has three tabs: Notifications, Settings and Information.
Notifications List
The Notifications tab lists every notification:
| Column | What it shows |
|---|---|
| Name | The admin-only name. Click it to open the notification. |
| Type | Alert, Modal or Floating Alert. |
| Start / End | The display dates, or – when none is set. |
| Priority | High, Normal or Low. |
| Stats (30 days) | Views and click rate over the last 30 days. |
| Status | Published or Disabled. A published notification outside its dates shows Scheduled (not started yet) or Expired (ended). |
| Actions | Publish/Disable toggle, Duplicate, Export and Delete. |
Use the search box to find a notification by name or type, and click a column title to sort by it. The toolbar has Add New and Import.
- Duplicate copies the settings, content and buttons, adds " (copy)" to the name and saves the copy as Disabled. Statistics are not copied.
- Delete removes the notification and its statistics. It cannot be undone.
Create a Notification
- In the Notifications tab, click Add New.
- Go through the steps and click Next after each one: Style, Content (required), Display Rules, Display Conditions and Name & Publish (required). Each step is explained below.
- Check the Summary. Click Edit next to any step to go back to it.
- Click Create & publish to show it right away, or Create as draft to save it as Disabled.
To edit a notification, click its name in the list. All steps open in a side menu, plus Statistics. Make your changes and click Save Changes. Notes that do not block saving (for example, a modal visitors cannot close) appear under Saved, with notes.
Display Rules
Display Rules decide where and to whom a notification shows. Rules are grouped in cards, each with an on/off switch:
- A card that is off is ignored.
- The notification shows when every card that is on matches.
- Inside a card, every filled field must match. A field with several values matches when any of them matches.
With every card off, the notification shows on every page to every visitor.
Page Filters
Choose where it appears in Show on:
- All pages.
- Page categories: Client Area pages, Order Process pages, or both.
- Specific pages: any mix of Client Area pages, Order Process pages, Product groups, Support departments and Custom URL.
Use Except on (optional) to hide it on some pages. An excluded page always wins over a selected one.
Custom URL: enter a page URL or keyword and choose is exactly or contains. Click Add more for more rows. Matching ignores upper and lower case.
Client Filters
| Field | What it does |
|---|---|
| Client status | Any, Logged in or Logged out. |
| Client(s) | Specific clients. Search by name, email or company. |
| Group | WHMCS client groups. |
| Country | The client's country. |
| Marketing emails | Opted in or Opted out. |
| Days since sign-up | Shows while the client signed up this many days ago or less. |
Every field except Client status applies to logged-in clients only. A guest never matches them.
Services Assigned
For logged-in clients. The client must own services that pass every filled field:
- Service(s), Status, Billing cycle, Server(s), Server group(s).
- Registration date and Next due date: one date or a range.
- Days until due date and Days after due date: one value or a range.
- Filtered services count: Disabled, None, Less than or More than a number of the services that passed the fields above.
When the selected products have configurable options, a field appears for each option.
Services Not Assigned
For logged-in clients. Shows only to clients who own none of the selected services. Use it to cross-sell, for example an SSL offer hidden from clients who already have one.
Domain Filters
For logged-in clients. The client must own domains that pass every filled field: TLD(s), Status, Registrar, Billing cycle, Registration date, Days since activation, Expiry date, Days until due date, Days after due date, and Filtered domains count.
Shopping Cart
Read from the visitor's current cart, for guests and clients:
| Field | Options |
|---|---|
| Cart items | Disabled, None (empty cart), Less than or More than a number. |
| Cart amount | Per currency: Disabled, Less than or More than an amount. |
| Cart products | Disabled, Contains all selected, Contains any selected, Contains none of selected. |
| Promo code | Disabled, Applied (any code, or a specific one), Not applied. |
Display Conditions
- Display close icon: lets clients close the notification. Off by default, so important messages stay visible.
- Show again (when the close icon is on):
- After every page reload.
- At the client's next login (guests: after every reload).
- After a number of days. Turn on Require confirmation checkbox to show a "Don't show this again" checkbox: the notification stays hidden only if the client ticks it.
- Never again after closing.
- Reset dismissals: click Reset to show the notification again to everyone who closed it. Editing the content does not reset dismissals on its own.
For logged-in clients, a dismissal is saved on the server and follows them across devices. For guests it is saved in their browser.
Style
| Setting | Options |
|---|---|
| Type | Alert: inside the page, under the title. Modal: a pop-up; several open one after another, never on top of each other. Floating Alert: a bar fixed at the top of the window, above the menu, that pushes the page down. |
| State | Default, Info, Success, Warning, Danger, Primary, Secondary or Gray. Colors come from your Phox color settings, in light and dark mode. |
| Buttons location | Alert and Floating Alert: Right or Bottom. Modal: Left, Center or Right. |
| Modal trigger | Page load (optional delay in milliseconds), Exit intent (opens when the mouse leaves the window; on touch devices it opens on page load instead), or Click. |
| Modal size | Small (300px), Medium (448px), Large (560px), Extra large (800px). |
| Display default icon | Shows the icon of the state. An icon chosen in Content replaces it. |
Click trigger: enter a Trigger class, for example open-promo-modal, and add that class to any link or button in your menu, theme or page content. Clicking it opens the modal. No JavaScript is needed.
Content
Language: pick a language at the top. Each language has its own title, message and button texts. An empty language shows the default language's content. Arabic and other right-to-left languages display right to left automatically.
Title: optional. Leave it empty for no heading, for example to show a full-width image at the top of a modal.
Message: write it in the Visual editor (bold, italic, headings, lists, links, alignment, images) or switch to HTML source. Emoji are welcome. Use Insert variable to add client data or a countdown (see Message Variables and Timer).
Preview: shows the notification as clients will see it, in light and dark mode.
Media Manager
Click Icon / image to open the Media Manager:
| Tab | What it holds |
|---|---|
| Predefined icons | Font Awesome icons, with search. |
| SVG illustrations | Larger drawings that follow your Phox colors. |
| Media library | Images you uploaded before. |
| Upload | PNG, JPG, GIF, WebP or SVG, up to 2 MB. |
Uploaded SVG files are cleaned of scripts for safety. An image used by a notification cannot be deleted until you remove it there.
Buttons
Click Add New under Buttons:
| Setting | Options |
|---|---|
| Size | Extra small, Small, Default, Large. |
| Style | Solid, Outline, Link. |
| Colour | Primary, Secondary, Default, Info, Success, Warning, Danger. |
| Text | Per language. |
| Link | Custom URL (http, https, mailto:, tel: or a path starting with /), WHMCS page (picked from a list such as Order / Store, Invoices, Open ticket, Network status) or Close notification. |
| Custom classes | Your own CSS classes. |
| Window | Open in a new window. |
| Icon | Optional icon. |
Use Move up and Move down to reorder buttons.
Message Variables and Timer
Click Insert variable in the message editor. Variables are replaced when the page loads.
| Variable | Shows |
|---|---|
{Client Name}, {Client First Name}, {Client Last Name}, {Client Email Address}, {Client Company Name} |
The client's details. |
{Services} / {Domains} |
The number of the client's services or domains that match this notification's filters. |
{Unpaid Invoices} / {Overdue Invoices} |
Number of unpaid or overdue invoices. |
{Total Due Invoices Balance} |
Total due, in the client's currency. |
{Client Credit Balance} |
Credit balance, in the client's currency. |
Guests: number variables show 0. Client details are empty, so add a fallback after a |: Hi {Client First Name|there}! shows "Hi Sarah!" to a client and "Hi there!" to a guest. If a notification can show to guests and uses a client detail without a fallback, you get a note on save.
Countdown Timer
{Alert Expiry Counter} counts down to the notification's end date. It needs Display time on with an End date.
| Option | Values |
|---|---|
| Style | Style-1 (default), Style-2 (bordered), Style-3 (boxed), Style-4 (separated). |
| Size | Default, Size-Small, Size-Extra-Small. |
| Type | Type-Reset: restarts every 24 hours from the start date until the end date. Needs a start date. |
Example: {Alert Expiry Counter Style-3 Size-Small}. The Insert variable menu builds it for you.
Name & Publish
- Name: only admins see it.
- Custom CSS class: added to the notification so your own CSS can style it.
- Publish: on shows it in the client area; off keeps it Disabled.
- Priority: High, Normal (default) or Low.
- Display time: show it only between a Start and an End date, in your WHMCS system time zone.
- Last modification: when it was last saved and by which admin.
Order and Limits
When several notifications match one page, higher priority comes first; with the same priority, the most recently published comes first.
| Type | What the order decides | Limit per page |
|---|---|---|
| Alert | Top-to-bottom order | No limit |
| Floating Alert | Top-to-bottom stacking | Floating alerts per page (default 2) |
| Modal | Which opens first; the next opens after the first is closed | Modals per page (default 1) |
Closed notifications free their place, so a lower-priority one can show on the next page load. Modals with the Click trigger are not counted.
Statistics
| Metric | Counted when |
|---|---|
| Views | The notification was actually shown. A notification hidden by a limit, or an exit-intent modal that never opened, is not a view. |
| Closes | The visitor closed it. |
| Clicks | A button was clicked, counted per button. A Close notification button counts as a click and a close. |
| Click rate | Clicks divided by views. |
Counts include clients and guests, once per visitor per day, so reloads do not inflate them. Bots and your own admin previews are ignored. Only daily totals are stored: no IP address, client ID or other personal data.
See the last 30 days in the Stats (30 days) column, or open a notification and go to Statistics for a Period (7, 30, 90 days or Custom) with totals, a daily chart and clicks per button. Reset statistics deletes the counts of that notification; it cannot be undone.
Import and Export
Export: click Export in the notification's actions to download a .zip with its rules, style, content, buttons and images (no statistics).
Import: click Import, choose the Upload .zip tab, select the file and click Import. The notification is created Disabled and its images are added to your media library. Clients, products, servers, groups and departments are kept by ID; any that do not exist on this install are listed so you can fix the rule. The .zip can be up to 32 MB, and import and export need the PHP zip extension.
The Predefined tab in the same dialog imports ready-made notifications. See Client Notifications Predefined Notifications.
Extension Settings
Open the Settings tab:
- General: Enable notifications (the global switch: off hides every notification in the client area), Modals per page (default 1) and Floating alerts per page (default 2).
- Storage: where uploaded images are kept, any storage set up in WHMCS Storage Settings, local or Amazon S3. Default: the one your Knowledgebase images use. Switching copies and checks every image first and only switches if all copies succeed. If your Knowledgebase uses a different storage, a notice offers to Move images there.
- Statistics: Collect statistics (on by default; off adds no tracking script and saves nothing) and Keep statistics for (days) (default 365).
- Translations: the client-facing words per language, such as Close and "Don't show this again".
- Danger zone: Delete all notifications and images. You must type the confirmation word; it cannot be undone.
Troubleshooting
A notification does not show. Check that its status is Published (not Scheduled or Expired), Enable notifications is on, every display rule card that is on matches you (client, service and domain filters never match guests), you did not close it before (use Reset dismissals or a private window), and a higher-priority modal or floating alert is not taking its place. Then clear the template cache in Utilities > System > System Cleanup.
Alerts do not show, but modals do. If you use a custom header in templates/phox/packages/overwrites/header.tpl, add this line inside div.main-content, right after the page title block:
{if isset($phoxClientNotifications.html.alerts)}{$phoxClientNotifications.html.alerts}{/if}No notifications on some pages. The invoice view, the quote view and OAuth pages do not use the Phox header and footer, so nothing shows there.
Import or export fails. The PHP zip extension is missing; the Information tab shows a warning. Ask your host to enable it.