# How to Configure the Client Notifications Extension

> Configure Client Notifications in WHMCS: create notifications, display rules, conditions, style, content, variables, countdown timer, statistics and settings.

Source: https://phox.wdes.org/docs/how-to-configure-the-client-notifications-extension/
Last updated: 2026-11-08

![Client Notifications](https://phox.wdes.org/docs/assets/client-notifications.CfJ2E8DN_Z1nDprb.webp)

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.

![Notifications list with a few notifications](https://phox.wdes.org/docs/assets/client-notifications-list.CvMWyc0s_1I11Qc.webp)

## Create a Notification

1. In the **Notifications** tab, click **Add New**.
2. 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.
3. Check the **Summary**. Click **Edit** next to any step to go back to it.
4. 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**.

![Add New steps with the Summary](https://phox.wdes.org/docs/assets/client-notifications-add-new.BmzmkOoF_g06Ca.webp)

## 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.

![Display Rules step with the filter cards](https://phox.wdes.org/docs/assets/client-notifications-display-rules.BM7rCIh9_Z24Mygs.webp)

### 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.

![Page filters card with a Custom URL row](https://phox.wdes.org/docs/assets/client-notifications-display-rules.BM7rCIh9_Z24Mygs.webp)

### 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.

> **Note:**
>
> A **modal** with the close icon off cannot be closed with Esc or a click outside it. Add a button with the **Close notification** link so visitors can dismiss it; otherwise you see a note when you save.

![Display Conditions step with the Show again options](https://phox.wdes.org/docs/assets/client-notifications-display-conditions.CVhZu_hX_1Pes7G.webp)

## 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.

![Style step](https://phox.wdes.org/docs/assets/client-notifications-style.NoolxzWw_ZNHss.webp)

## 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](https://phox.wdes.org/docs/how-to-configure-the-client-notifications-extension/#message-variables-and-timer)).

**Preview:** shows the notification as clients will see it, in light and dark mode.

![Content step with the editor and the live preview](https://phox.wdes.org/docs/assets/client-notifications-content.BkHMdZfq_1HYtXj.webp)

### 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.

> **Tip:** Tip for designers
>
> Add your own SVG files to `templates/phox/packages/client-notifications/icons/` or `.../illustrations/`. They appear in the Media Manager. Use lowercase names with dashes (e.g. `black-friday.svg`) and keep each file under 100 KB. To make an icon take the notification's colour, use `fill="currentColor"` or `stroke="currentColor"` instead of fixed colours. `<style>` blocks and scripts are removed.

![Media Manager with its tabs](https://phox.wdes.org/docs/assets/client-notifications-media-manager.THkKajiW_Z2lBa6c.webp)

### 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.

![Button edit form](https://phox.wdes.org/docs/assets/client-notifications-button.CeBH6eGK_28WoNN.webp)

## 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.

![The four countdown timer styles in the client area](https://phox.wdes.org/docs/assets/client-notifications-timer-styles.DFDOxnI6_ZHPxnX.webp)

## 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.

![Name & Publish step](https://phox.wdes.org/docs/assets/client-notifications-name-publish.V-QRa4nL_Z1Gt3px.webp)

### 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.

![Statistics section with the daily chart and clicks per button](https://phox.wdes.org/docs/assets/client-notifications-statistics.C6AS5v25_Z2oy8za.webp)

## 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](https://phox.wdes.org/docs/client-notifications-predefined-notifications/).

![Import Notification dialog](https://phox.wdes.org/docs/assets/client-notifications-import.BQLwR3b6_1kHbAy.webp)

## 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.

![Settings tab](https://phox.wdes.org/docs/assets/client-notifications-settings.BQdCILF8_Z1iQSGm.webp)

## 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.