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)

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.

Note: the modern widget_page_rules.rules[] schema does not include a per-page launcher_style field. 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 an is_default flag.
• 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 (/products matches /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 url string 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: call rule is silently ignored for a company that has disabled both call channels (it is not downgraded to chat).
• duration: 0 fires 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.
• Staging URLs often don't match production patterns — test on real URLs.
• Order of precedence (top wins): (1) show_only_on_pages allow-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 !noxForced in calculateLeadAutoConnectMessage, 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 the nox-auto-engage-message socket (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 and canShowAutoTrigger().
• 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.

Related

• Widget Types & Launcher Styles
• Working Hours
• Styles & Appearance
• Installation