Skip to main content

Auto-Triggers

Audience: Sales · Support · QA · Management · Engineering · Where in app: Settings → Widget → Auto-Triggers · monitored on the Auto Engage dashboard · Plan availability: All plans (verify any tier gating)

Auto-triggers are the proactive flavor of engagement: instead of waiting for a visitor to click, the widget reaches out first. There are two independent systems — an AI chat auto-trigger (a chatbot bubble pops up with a greeting) and a call auto-trigger (an auto-connect video/call popup, often a pre-recorded sales-rep greeting). Both fire based on which URL the visitor is on and how long they've lingered, and both feed lead scoring when the visitor engages.

What it does​

  • Proactively opens a chat bubble (AI auto-trigger) or a call/video popup (call auto-trigger) for the visitor.
  • Targets specific pages via URL rules and waits a configurable dwell time before firing.
  • Suppresses itself if the visitor was already triggered this session, the page is hidden, or the widget is offline (unless configured for offline).
  • Awards lead-score points when the visitor accepts/replies, which can push them over the hot-lead threshold.
  • Is measured on the Auto Engage dashboard (fires, acceptance rate, top URL rules).

How it works​

1. AI auto-trigger (chat pop-up)​

Config root: companies.ai_auto_trigger.

When eligibility is met, the widget shows a chat bubble with a greeting message (server emits chatbot-auto-trigger, which increments auto_triggers_count on the chat). If the visitor types back, a full chat starts under the AI Chat Agent. After ~5 messages, ms-communication builds a summary and notifies agents via the chat-summary socket event (headline, urgency, issue, contact info).

Dedupe: the widget writes kk_ai_auto_triggered_at to localStorage so the trigger doesn't re-fire on every page load within the cooldown.

2. Call auto-trigger (auto-connect video popup)​

Config root: companies.call_auto_trigger (plus the CallAutoTriggerModel for URL targeting).

When eligibility is met, the visitor sees a video-call-style popup (agent video + accept/decline), optionally with a ringtone. On accept, the call routes to the AI voice agent or a live agent per call_routing, and the configured pre-recorded video plays as the greeting. In the widget call config this is createdBy: 'auto_trigger' with an optional autoTriggersMessage.

Eligibility logic (both types)​

A visitor sees an auto-trigger when ALL of:

  1. The current URL matches a configured rule.
  2. The visitor hasn't already been triggered this session (localStorage flag, e.g. kk_ai_auto_triggered_at).
  3. The visitor has been on the page for at least the configured dwell time (duration / display_time).
  4. The widget is online per working hours (or the trigger is configured to work offline).
  5. The widget isn't suppressed by mobile_disable or a page rule's hide_on_pages.

Configuration & options​

AI auto-trigger (companies.ai_auto_trigger)​

FieldMeaning
enableMaster switch
ai_model / ai_model_providerWhich LLM powers the conversation
system_instructionsThe chatbot persona/instructions
threshold (default 50)Internal engagement-score threshold to fire
default_messagesPool of default greetings
agent_name / agent_photoHow the chatbot presents itself
url_rules[]Per-URL overrides (see below)

url_rules[] entries:

FieldMeaning
urlGlob pattern to match the page
trigger_typechat or call
durationSeconds of dwell before firing
messageCustom greeting for this rule

Call auto-trigger (companies.call_auto_trigger)​

FieldMeaning
is_activatedMaster switch
display_time (default 15s)Page dwell before the popup
auto_connect_video_file (ObjectId)Pre-recorded greeting video (uploaded via Default Videos → FileModel)
has_audioWhether the video plays audio
enable_ringtonePlay a ring sound when the popup appears
auto_connect_agent_name / auto_connect_messagePresenter name and message
call_background.background_color / .background_imagePopup background
text_colorPopup text color

URL targeting: the CallAutoTriggerModel holds company_id + page_urls[] (list of URL patterns the call auto-trigger fires on). Configured under Widget Setup → Auto-Triggers.

Behaviors & edge cases​

  • Once per session. The localStorage flag (kk_ai_auto_triggered_at for AI; an equivalent guard for call) prevents repeated triggers on every page load. Clearing localStorage / a fresh incognito session re-arms it — useful for QA testing.
  • Dwell timing. The AI trigger uses the rule's duration; the call trigger uses display_time (default 15s). The timer counts on-page dwell, not total session time.
  • Offline handling. By default auto-triggers respect working hours; a trigger can be configured to also fire offline. If offline and not configured for it, nothing pops.
  • Mobile / page suppression. mobile_disable and a page rule's hide_on_pages will suppress the widget (and therefore any trigger) entirely.
  • Engagement → lead score. When a trigger fires and the visitor engages (replies to chat / accepts the call), lead_score.chat_auto_connect_accepted or lead_score.call_auto_connect_accepted points fire, climbing the visitor's lead score and potentially crossing the hot-lead threshold (which itself can fire a Slack/hot-lead notification — see Notifications).
  • Engagement-score threshold (AI). The AI auto-trigger has an internal threshold (default 50); the bubble fires when the computed engagement score clears it, in addition to the URL/dwell gates.
  • Nox can read, not toggle. Nox can report whether auto-triggers are enabled, which URL rules exist, recent fire counts (from session analyses), and acceptance rate — but it cannot turn them on/off; that's an admin edit in Widget Setup → Auto-Triggers.

Common patterns (for sales/onboarding)​

  • High-intent pages (/pricing, /contact): low duration (5–10s), persuasive message, trigger_type: chat.
  • Demo pages: trigger_type: call with a pre-recorded sales-rep video greeting.
  • Onboarding pages: trigger_type: chat, help-oriented ("Need help getting started?").
  • Blog/long-read pages: long duration (30–60s) so readers aren't interrupted.

Plan & limits​

  • Auto-triggers are documented as available on all plans.
  • No hard fire-count limit is documented; throttling is the once-per-session localStorage guard plus dwell-time gating. Heavy use of AI auto-triggers consumes AI credits (the chat that follows is a normal AI chat).
  • Any tier gating on the Auto Engage analytics dashboard or pre-recorded video uploads — verify.

Technical implementation​

  • Config & models: companies.ai_auto_trigger, companies.call_auto_trigger, and CallAutoTriggerModel (URL targeting); pre-recorded videos as FileModel entries.
  • Widget: widget — evaluates eligibility per URL/dwell, manages the localStorage guards (kk_ai_auto_triggered_at), and renders the chat bubble / call popup. Call popups go through src/services/call.ts (createdBy: 'auto_trigger'); AI voice via src/services/aiCall.ts.
  • Real-time: ms-communication emits chatbot-auto-trigger (fire) and chat-summary (post-engagement summary) over socket.io; see app/controllers/MessageController.js. See ms-communication.
  • Lead scoring & analytics: scoring points (*_auto_connect_accepted) and the Auto Engage dashboard are driven by session analyses; see Nox Assistant for what Nox can report.