Page Rules
Audience: Sales · Support · QA · Engineering · Management · Where in app: Settings → Widget → Rules tab (auto-triggers under Widget Setup → Auto-Triggers) · Plan availability: All plans
Page rules let an admin make the widget behave differently depending on which URL the visitor is on. There are several distinct mechanisms — they look similar but live in different config objects and are edited in different places. The most common uses: show a different heading on the pricing page, pop the AI chatbot open on high-intent pages after a few seconds, or hide the widget entirely on the checkout and admin pages.
What it does
- Appearance rules override the launcher heading, subheading, and video on matching URLs.
- AI auto-trigger URL rules decide whether (and how) the AI chatbot or AI call pops up automatically on a URL.
- Call auto-trigger drives an auto-connect call popup on configured pages.
- Hide-on-pages suppresses the widget entirely on listed URLs.
How it works
Type 1 — Widget appearance rules (companies.widget_page_rules)
Enabled by widget_page_rules.is_enable. Each entry in widget_page_rules.rules[] matches a URL and overrides per-page content.
| Field | What |
|---|---|
url | URL pattern to match |
heading | Launcher heading when online |
sub_heading | Launcher subheading (online or offline) |
offline_heading | Heading used when outside working hours |
video_file_id | Override the launcher/preview video on this page (FileModel id) |
video_has_audio | Whether that media has sound (2026-09) — false hides the widget's mute button |
Matching is performed by findPageRule(): both the current URL and the rule URL have all slashes stripped, then it matches if they are equal or the current URL contains the rule URL. This is a loose "contains" match, not a strict glob — keep that in mind when authoring rules. First match wins. Rules are applied only after the real parent-page URL arrives via postMessage.
Rule media and the mute button (widget e57a41c, frontend e1ce1621, backend c80e1468e / ms-comm 4c6b1b0 add the schema field). A rule's upload may be a video or an image ("Upload Video or Image"; validated client-side by common/helpers/welcomeMedia.js — video ≤45 s and ≤45 MB, image ≤20 MB — and converted server-side to a looping MP4). The frontend sets video_has_audio: !isImage on upload, and on save copies the company's widgetvideo_audio onto a rule that reuses the default video. The widget store's pageRuleHasAudio() sets videoHasAudio when a rule matches: the stored boolean if present; else the company's widgetvideo_audio when video_file_id equals the company video_file; else true (legacy rules held videos only). Every launcher (Bar, Bubble, Smart, Ultimate, Welcome, VideoCallPromo) renders the mute button only when store.videoHasAudio. The settings preview passes the active rule's hasAudio and shows a pending image as the video poster.
Note: the modern
widget_page_rules.rules[]schema does not include a per-pagelauncher_stylefield. Per-page launcher-style switching referenced in older material should be treated as verify.
Type 2 — AI auto-trigger URL rules (companies.ai_auto_trigger.url_rules)
Each rule decides whether the AI chatbot or AI call auto-opens on a URL. Requires the master switch ai_auto_trigger.enable = true.
| Field | What |
|---|---|
url | URL pattern (path, full URL, or …/* wildcard) |
enabled | Per-rule on/off |
trigger_type | chat or call — what pops up (default chat) |
duration | Seconds the visitor must dwell before it fires (default 5; 0 = immediate) |
message | Custom greeting; falls back to the default flagged message in default_messages[], else "Hey! Need help with anything?" |
Global controls in ai_auto_trigger:
enable— master switch.threshold— score threshold (default referenced as 50; scoring is internal).default_messages[]— list with anis_defaultflag.agent_name/agent_photo— identity for the trigger card (falls back to first team member, then AI chat/call agent, then "AI Assistant").
Matching here (findAutoTriggerUrlRule) is stricter than appearance rules: it extracts the pathname, lowercases it, strips trailing slashes, and supports:
…/*wildcard (prefix match, e.g./products/*),- exact path match,
- prefix match (
/productsmatches/products/widget-pro).
Type 3 — Call auto-trigger (companies.call_auto_trigger)
When is_activated (the KB also references enable), an auto-connect call popup appears after display_time seconds (default ~15). It can play a custom auto-connect video, optional ringtone/audio, and uses a configured agent name, message, and call background.
| Field | What |
|---|---|
is_activated | Enable the call auto-trigger |
display_time | Seconds before the popup shows |
auto_connect_video_file | Video played in the popup (FileModel id) |
has_audio | Whether the auto-connect video has audio |
enable_ringtone | Play a ringtone |
auto_connect_agent_name | Agent name shown |
auto_connect_message | Popup message |
call_background.background_color / .background_image, text_color | Call popup styling |
Type 4 — Hide on pages / show only on pages
Page-visibility lists on companies.widget_page_rules, enforced by the loader
(backend/public/widget.js) before the iframe is rendered:
companies.widget_page_rules.hide_on_pages = ["/checkout", "/admin"] // block-list
companies.widget_page_rules.show_only_on_pages = ["/pricing", "/demo"] // allow-list (new)
show_only_on_pages[]— when non-empty, the widget renders only on matching pages.hide_on_pages[]— never render on matching pages; applies even within the allow-list.- Entries may be a path (
/pricing) or a full URL; matching is loose (trailing-slash-stripped, lowercased, equality or path-contains). - Session tracking still runs on excluded pages — only the iframe render is skipped.
Channel availability is company-wide
Page rules do not turn channels (chat/video/audio) on or off per page — that is governed company-wide by communication_options. To remove video on one page you must disable it company-wide or use a dedicated landing page.
Configuration & options
| Mechanism | Config object | Edited in |
|---|---|---|
| Appearance override | companies.widget_page_rules.rules[] | Settings → Widget → Rules |
| Hide on pages | companies.widget_page_rules.hide_on_pages[] | Settings → Widget → Rules |
| Show only on pages | companies.widget_page_rules.show_only_on_pages[] | Settings → Widget → Rules |
| AI auto-trigger | companies.ai_auto_trigger.url_rules[] + globals | Widget Setup → Auto-Triggers |
| Call auto-trigger | companies.call_auto_trigger | Widget Setup → Auto-Triggers |
Behaviors & edge cases
- Two different matchers. Appearance rules use loose, slash-stripped "contains" matching; AI auto-trigger rules use stricter path/wildcard/prefix matching. The same
urlstring can behave differently between the two. - First match wins for appearance rules; for auto-trigger, the first enabled matching rule is used.
- Chat-only companies skip call-type triggers. A
trigger_type: callrule is silently ignored for a company that has disabled both call channels (it is not downgraded to chat). duration: 0fires the auto-trigger immediately — useful on high-intent pages.- Re-trigger / retry: if the visitor closes an auto-trigger, the widget retries on a back-off (roughly 1 min, 1 min, then 3 min, with a call-type retry auto-closing after ~30s). User interaction with the widget suppresses further auto-triggers.
- Customers get no sales pop-ups (widget
f4c89aa): whenGET /get-user-session/:idreturnsusersession.sales_suppressed(a Won contact on a company whose Nox Funnelcustomers.modeisstop_selling, resolved by backendcustomers.skipCustomer, fail-open),canShowAutoTrigger()returns false — no lead-score, URL-rule or default-message auto-trigger. Opening chat still works. - Staging URLs often don't match production patterns — test on real URLs.
- Order of precedence (top wins): (1)
show_only_on_pagesallow-list (when non-empty, page must match); (2)hide_on_pages→ widget doesn't render (even inside the allow-list); (3) AI auto-trigger URL rule → controls the auto-popup; (4) appearance page rule → heading/subheading/video; (5) company-level defaults. - Nox admin-forced engage bypasses the heuristic suppressors (15/30-min cooldowns, 48h agent-connected window, manual URL rules — guarded by
!noxForcedincalculateLeadAutoConnectMessage,widget/src/stores/widget.ts); hard blockers still apply (document.hidden, user interacting with the widget, incoming/missed call, call in progress). A server-pushed variant arrives via thenox-auto-engage-messagesocket (ms-communication).
Plan & limits
- All page-rule mechanisms are available on all plans.
- AI auto-trigger / AI call require the relevant AI features to be enabled on the company (verify any per-tier AI gating against the AI plan matrix).
Technical implementation
- Store logic:
widget/src/stores/widget.ts—findPageRule(),applyPageRules(),findAutoTriggerUrlRule(),triggerUrlRuleAutoConnect(), plus the auto-trigger retry timers andcanShowAutoTrigger(). - Types:
widget/src/types/company.ts—WidgetPageRule,WidgetPageRules,AIAutoTriggerUrlRule,AIAutoTrigger,CallAutoTrigger. - Trigger UI:
widget/src/components/AIAutoTriggerChat.vue,AIAutoTriggerCall.vue. - Admin UI:
frontend/src/views/settings/widget/tabs/RulesTab.vue. - See the engineering service page: /services/widget. Auto-trigger scoring and the insight engine are owned by the AI subsystem — see /subsystems/nox-assistant.