Skip to main content

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.

FieldWhat
urlURL pattern to match
headingLauncher heading when online
sub_headingLauncher subheading (online or offline)
offline_headingHeading used when outside working hours
video_file_idOverride the launcher/preview video on this page (FileModel id)
video_has_audioWhether 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-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.

FieldWhat
urlURL pattern (path, full URL, or …/* wildcard)
enabledPer-rule on/off
trigger_typechat or call — what pops up (default chat)
durationSeconds the visitor must dwell before it fires (default 5; 0 = immediate)
messageCustom 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.

FieldWhat
is_activatedEnable the call auto-trigger
display_timeSeconds before the popup shows
auto_connect_video_fileVideo played in the popup (FileModel id)
has_audioWhether the auto-connect video has audio
enable_ringtonePlay a ringtone
auto_connect_agent_nameAgent name shown
auto_connect_messagePopup message
call_background.background_color / .background_image, text_colorCall 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​

MechanismConfig objectEdited in
Appearance overridecompanies.widget_page_rules.rules[]Settings → Widget → Rules
Hide on pagescompanies.widget_page_rules.hide_on_pages[]Settings → Widget → Rules
Show only on pagescompanies.widget_page_rules.show_only_on_pages[]Settings → Widget → Rules
AI auto-triggercompanies.ai_auto_trigger.url_rules[] + globalsWidget Setup → Auto-Triggers
Call auto-triggercompanies.call_auto_triggerWidget 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.
  • Customers get no sales pop-ups (widget f4c89aa): when GET /get-user-session/:id returns usersession.sales_suppressed (a Won contact on a company whose Nox Funnel customers.mode is stop_selling, resolved by backend customers.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_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.