Skip to main content

Nox Funnel

Behaviour-derived lead stages: cold → intermediate → warm → booked, plus a manual terminal won and a very-warm priority flag (not a stage). backend owns the engine (derivation, jobs, GHL writes); ms-ai only relays it to Nox via tools and brief blocks; frontend renders the Funnels page (Monitor → Funnels, /funnel). Available to every company since 2026-10-09 and switched on for every company since 2026-11-06 — the tenant's nox_funnel.enabled is the only switch (see Gating and Enable-for-all rollout). Every funnel contact is also a row on the Leads page (Leads v2 — see Leads — Overview).

signal sources engine (backend)
GHL webhooks (opens/clicks/tags) ─┐
kk-click / web visits ─┤
FunnelSweepJob (sessions/calls/ ─┼─► FunnelStageService.recordSignal()
chats, every 10 min) ─┤ dedupe → $inc counter → derive stage
ms-ai conversation outcomes ─┘ (upward-only) → very-warm flag
│
stage change ──► GHL stage-tag mirror (`nextlevel stage:<stage>`)
very-warm flip ──► NoxFunnelInterceptService (in-app + push, capped)
nightly ──► FunnelDormancyJob (step-down demotion)
NoxFunnelReconcileJob (behaviour vs mapped GHL pipeline)

Stages​

StageHow it's earned
coldentered the funnel (Agent K push, feed tag, form, opportunity seed)
intermediatefirst visit/open/click, opens ≥ email_open_threshold (3), answered call, reply, chat, score_bands.intermediate
warmvisits ≥ 2, session ≥ 120s, high-intent pages, re-open days ≥ 2, multi-link clicks, score_bands.warm; instant-warm signals (instant_warm_signals, default booking_start)
bookeda booking — on any calendar, or only the booking_calendar_ids allowlist when set (c37b5e9ac; every appointment still mirrors into the identity graph, only the funnel signal is gated)
wonterminal — moveToWon (Mark as won, Nox knox_mark_customer, Jobber payment), a booking on a won_calendar_ids calendar, or a won-mapped pipeline stage / feed tag; behaviour never derives it and decay never demotes it

very_warm is a flag with expires_at (demotion.very_warm_hold_days, 14d, re-extended by engagement). OR-rules in FunnelStageService.deriveVeryWarm: same-day visits ≥ 2, one campaign opened ≥ 4×, contact shared, positive conversation, multi-channel within 24h, spike vs baseline, score band. Only the v2 very-warm rules lift the stage to warm; the other OR-rules raise the flag and leave the stage on the ladder (ca122a31c). Promotion is upward-only; demotion belongs exclusively to the dormancy job (step-down one stage at a time, with a stage_baseline snapshot the contact must re-earn against). conversation_negative demotes one step immediately.

Data model (backend)​

CollectionModelNotes
funnel_contactsapp/models/FunnelContactModel.jsone doc per (company, contact), keyed by ghl_contact_id OR person_id (partial-unique each; merged on stitch). $inc signal counters, recent_signals[] window, stage_history[], very_warm{}, won_details{}
nox_funnel_audit_logsNoxFunnelAuditLogModel.jsevery decision (dedupes, gates, flips, intercepts) — TTL 120 days (live deployments need a manual collMod)
funnel_daily_statsFunnelDailyStatsModel.jsper (company, local day) census/transitions/dwell — the math engine's input
funnel_reconciliation_itemsNoxFunnelReconItemModel.jsbehaviour stage vs CRM layer mismatches, deduped review queue
brief_offersBriefOfferModel.jsexecutable brief offers, valid_until ≈ 48h (read-time gate, no TTL delete)
lead_lifecycle_eventsLeadLifecycleEventModel.jsappend-only lifecycle (stage_changed, showed, closed_won, …)

Config lives in company.nox_funnel.* (strict subdoc — undeclared keys drop silently): thresholds.* (incl. chat_messages_warm, default 3 — settings-editable), score_bands, demotion.* (90/60/14/14 days), feeding.{tags, tag_rules[{tag,stage}], forms_enabled, web_visitors_enabled, opportunities_enabled, last_sync_summary} — web_visitors_enabled = "feed from identified website visitors" (identified visitors may CREATE members; off = their signals still count for existing members); tag_rules.stage and pipeline_mapping.layer now accept won (customer tag/stage → enters as customer, not open lead; won stays terminal — reconcile promotes silently, never queues won for demotion), high_intent_pages, instant_warm_signals, stage_tag_prefix (default nextlevel stage:, blank = off — unchanged), goals.monthly_booked_target, pipeline_mapping.pipelines[{pipeline_id,stage_id,layer}], actions.{workflow_trigger_mode, frequency_cap, standing_rules}, intercept.enabled, outcomes.{positive_intermediate, positive_warm, positive_very_warm, negative_demotes} (conversation-outcome toggles; the first two default false, 91073e0f4), learned.{thresholds,history} (self-learning). Added 2026-09: reconciliation.{auto_promote, auto_demote} (both default false — NoxFunnelReconcileJob._autoApply runs after each scan with action: 'add_tag', actor job:NoxFunnelReconcileJob); pipeline_mapping.layer enum gains ignore (contacts seen only in ignored stages are deleted from the funnel after a healthy, non-truncated scan, never won; summary key removed_ignored); thresholds.link_clicks_intermediate (default 1; PATCH enforces 1 ≤ intermediate < multi_link_clicks_warm); booking_calendar_ids: [String] (default [] = any calendar; GET …/nox-funnel/ghl-options also returns calendars: [{id, name, isActive}], and a calendar deleted in GHL no longer fails a settings save, 3fa5cfcd7). Very-warm lists (overview, internal endpoint, brief) exclude won. Added 2026-11 (76b4d9154): won_calendar_ids: [String] (UI "Customer calendars" — a booking there marks the contact Won and never counts as a sales booking; "Sales calendars" = booking_calendar_ids) and customers.mode stop_selling (default) | keep_selling, read by lib/customers (skipCustomer, fail-open): with stop_selling, Agent K rules, push, sequences, campaigns, re-engage, KnoxAutoEngageService and widget pop-ups skip customers (Won or flags.customer); a rule's conditions.customers include/only overrides. rollout_enabled_at (stamped by the rollout, for undo) and backfill.{history_done_at, tokens_cursor} (FunnelBackfillJob state). New companies default enabled: true and stage_tag_prefix: '' (function defaults on isNew — existing docs without a stored value still read enabled: false / nextlevel stage:).

Jobs (backend SchedulerService)​

JobScheduleDoes
FunnelSweepJobevery 10 minfolds session analyses / calls / chats into recordSignal (20-min lookback, dedupe-safe); expires very-warm, hydrates names, merges duplicates, and re-syncs drifted stage tags (_resyncStageTags)
FunnelDailyStatsJobhourly (once per local day)yesterday's census rollup into funnel_daily_stats
KnoxGhlSyncJob03:00 UTC(pre-existing) GHL sync the funnel jobs depend on
FunnelDormancyJob04:00 UTCstep-down demotion, very-warm hold expiry, reactivation flagging
NoxFunnelReconcileJob04:30 UTCmapped-pipeline scan → recon queue; feed-tag scan; closed-won/lost polling
FunnelBackfillJob05:00 UTC nightly + admin "Run backfill" (background job, force re-imports)history (lifecycle replay of events older than the funnel's first contact + person-profile bookings) runs once per company (backfill.history_done_at); Agent K kk_tokens seed incrementally from backfill.tokens_cursor (eea30b77a). The nightly full replay double-counted live email signals (prod 2026-10-26: 150 extra signals, 11 stage changes in one night) and cost ~4 min of +20% Mongo CPU. Funnel reset clears the state so it rebuilds
FunnelFirstImportJobhourly at :20paces first history imports (≤20 companies, 30-min budget per run) so a fleet-wide enable can't run them all at once; the nightly job skips companies still awaiting theirs
NoxFunnelLearningJobMon 05:00 UTCdemote-only self-learning: repeated rejections (n≥5, ≥60%) raise a threshold one notch into nox_funnel.learned
DailyBriefEmailJobevery 10 min ticksends the brief once/local-day at knox.daily_brief.send_hour (default 9; funnel tenants set 5)

Very-warm intercept​

app/services/NoxFunnelInterceptService.js — fired in-process on a very-warm flip: in-app + push notification + nox-funnel-very-warm socket. Redis-capped 1/contact/day and 5/company/hour (code constants; fails open without Redis). Throttles are audited (intercept_throttled).

GHL integration​

  • Feeding — contacts carrying a feeding.tag_rules tag enter at that stage (upward-only against an earned stage); legacy flat feeding.tags reads as all-cold. Forms and mapped-pipeline opportunities can also seed members (forms_enabled / opportunities_enabled).
  • Stage-tag mirroring — every GHL-linked member carries <stage_tag_prefix><stage> (cold included) and no other stage tag. FunnelStageService.syncStageTag() is awaitable and serialized per contact via _tag_chains (f9f67b101): two moves in one tick used to interleave remove/add and leave a contact carrying two stage tags. The reconcile add_tag and the move fallback write through it. Since de910324b the write adds before it removes (the old order left a contact with no stage tag when the add failed) and stamps funnel_contacts.tag_synced_at + tag_synced_stage. A blank prefix (mirroring off) returns without stamping, so the contact stays owed.
  • Stage-tag catch-up — the mirror write is fire-and-forget, so one GHL 429 used to drift a contact forever, and members entering at cold were never tagged at all. FunnelSweepJob._resyncStageTags() picks up to 500 GHL-linked docs with tag_synced_stage != stage (unindexed $expr scan), excluding companies whose nox_funnel.stage_tag_prefix is blank (read live, not from the config cache); attempts ≤100 per run, memoizes each for 6h. It reads the contact first (re-adding a held tag can re-fire tenant workflows): right tag present → only removes leftover stage tags (scrubs the pre-2026-09 double-tag residue) and stamps; otherwise → syncStageTag, including a first tag (c9beec5b3, 2026-10-01 — previously the sweep refused to introduce one, so cold leads never got nextlevel stage:cold). A 400 "not found" stamps and moves on. Mirroring-off tenants are never stamped, so setting a prefix later tags their whole funnel in sweep-paced batches — and fires any tag-triggered workflows. Pre-existing docs have tag_synced_stage: '', so the deploy itself tagged every GHL-linked member once (read-before-write keeps it idempotent). Merging duplicates now mirrors the kept stage and no longer drops flags.customer.
  • Pipeline mapping — pipeline_mapping maps GHL pipeline/stage → funnel layer; the reconcile job compares behaviour stage vs mapped location and queues mismatches for owner approval (knox_funnel_reconcile in chat, or the dashboard Reconciliation panel). movePipeline falls back to a tag (mode: 'tag_fallback') when GHL scopes refuse the write.
  • Outbound sends go through NoxGhlActionService.checkOutboundAllowed (actions.frequency_cap, default 2 sends / 7 days / channel).
  • Scan report — the reconcile/manual sync persists what it did (scanned / seeded / skipped-unmapped / mismatches / truncated) to feeding.last_sync_summary, surfaced on the settings page (console output is unviewable in prod).
  • Rate-limit resilience — withGhlBackoff on searchOpportunities (a swallowed 429 read as a short page and silently truncated the board scan), stage-tag sync writes, and hydrateIdentity.getContact; HighLevel SDK clients use logLevel 'none' (the SDK dumped bearer-token prefixes on handled errors).
  • Deleted-contact self-cleanup — a definitive 400 "Contact not found" nulls the kk_token's ghl_contact_id and deletes the funnel doc only when cold with zero signals; audited ghl_deleted_cleanup.
  • Backfill fixes — seeds only Agent-K-pushed kk_tokens: source $nin ['ghl_backfill', 'manyreach'] (de910324b). The kk-token backfill and the saveContact hook stamp a ghl_backfill token on the tenant's entire CRM, so seeding every token with a contact id imported whole address books labelled agent_k. Legacy ''-source tokens predate the field and are pushes. (The one-shot funnel source repair that relabelled already-landed rows — lib/funnelSourceRepair.js, /admin/nox-funnel/source-repair — ran in prod and was deleted 2026-11-16 in the migration cleanup, 44820dc7e.) Reconcile pipeline scan cap 10 → 200 pages (below-board-size cap re-read the same first 1,000 opportunities forever); ensureContact(hydrate:false) for bulk seeds (was a 7k-call GHL 429 storm — the sweep's paced _hydrateUnnamed repairs names instead).

Gating​

Tenant nox_funnel.enabled ("Track the funnel") is the only switch. The super-admin nox_funnel_beta_enabled field, its PUT /company/:_id/nox-funnel-beta toggle and the admin Detail.vue switch were removed 2026-10-09 (backend 1f9742dc8, frontend ac19403a); the settings API (NoxFunnelSettingsController._fetchCompany) no longer 403s, and the Settings → Funnel menu item shows for everyone with settings.organization. FunnelStageService.getConfig() returns null while nox_funnel.enabled is off — fully dark, no writes, no audit (the old signal_gated audit row for "beta on, tenant off" is gone). Every !cfg guard keys off that.

Enabling no longer moves the brief to 5am — that lived in the removed toggle. The brief-send-hour and reason-text backfill endpoints were one-shots and are gone (44820dc7e).

The Funnels menu item (Monitor) shows only while nox_funnel.enabled is true; the settings page is always reachable.

No-CRM companies (ca122a31c, frontend 59078a35, 37c6b528)​

The funnel runs without a CRM: members are keyed by person_id, and journey, audit, notes, deals and tasks resolve a no-CRM contact by person id (and a non-GHL contact by its CRM id). Bookings from calendars with no CRM webhook record the booked signal (BookingRecordService). The duplicate-merge pass skips companies with no CRM and walks a cursor. The UI hides sync, feed tags, stage-tag prefix, workflow mode, auto-tag and the reconciliation panel (overview.crm_connected === false), and the contact modal opens by person id (no CRM link for person / mbx_ ids).

Enable-for-all rollout​

lib/funnelEnableRollout.run({ apply, noCrmOnly, limit, undo }) switches the funnel on for non-archived companies with an active subscription (distinct subscriptions.company_id with subscription_status: 'active') that don't have it on — quietly: unless the company already mapped pipelines or set feed rules, it also sets stage_tag_prefix: '' (no CRM tag writes) and intercept.enabled: false (no very-warm pushes). Each enabled company is stamped rollout_enabled_at, so undo only switches off what the rollout switched on. Super-admin POST /admin/nox-funnel/enable-rollout runs it as a background job (dry run unless apply: true) polled via GET /admin/nox-funnel/jobs/:job_id; UI: the "Enable the funnel for existing companies" MigrationPanel on Admin → Nox Funnel audit logs (views/admin/nox-funnel/AuditLogs.vue). First history imports then pace through FunnelFirstImportJob. New companies start enabled by default.

Fixes shipped for the rollout: the sweep passed normalizePhone's result object as the phone (answered calls and most WhatsApp/SMS replies failed a cast and never counted); last_engagement_at uses $max so a replayed old event can't make an active contact look dormant; merge data loss; a manual drag-down not sticking; re-arming very-warm after a negative outcome; lost visit length; sweep truncation; replay side effects; reconcile reopen; the tag-rule gate.

Endpoints​

  • Tenant (app/routes/noxFunnelRoutes.js): GET /knox/funnel/overview, /contacts, /call-prep, /contacts/:id/journey, /contacts/:id/audit, /contacts/:id/deal, /tasks, /reconciliation; POST /contacts/mark-won, /contacts/move-stage, /contacts/:id/deal, /contacts/:id/notes, /tasks, /tasks/:id/done, /reconciliation/apply, /reconciliation/:id/dismiss. :id is the GHL contact id, another CRM's id, or the person id for no-CRM contacts.
  • Settings (CompanyRoutes.js → NoxFunnelSettingsController): GET/PATCH /company/:id/nox-funnel, POST …/nox-funnel/sync, POST …/nox-funnel/reset (danger zone — deletes funnel contacts, recon items, daily stats + clears learned; audit logs kept, incl. a funnel_reset row; feeds untouched — backfill/sync rebuilds), GET …/nox-funnel/ghl-options.
  • Admin (adminNoxFunnelRoutes.js): GET /admin/nox-funnel/audit-logs, /contacts/trace, /jobs/:job_id; POST /backfill ({company_id, force}, background job) and /enable-rollout.
  • Stage lists (GET /knox/funnel/contacts) sort last_engagement_at, updated_at, _id — without the _id tiebreak cold contacts (null engagement, updated_at moving under the cursor) repeated across pages. FunnelBoard.vue also dedupes on append and pages off the server's page count, not items.length (920e9788).
  • Internal ms-ai → backend (internalKnoxRoutes.js): GET /internal/knox/funnel/{contact,summary,stats,priorities,reconciliation}, POST …/actions/{tag,move,trigger-workflow,book-meeting,mark-customer}, …/reconciliation/apply, …/conversation-outcome, …/suggestion-decisions; brief: GET /internal/knox/brief/{snapshot-data,sections,offers}, POST …/offers/:id/resolve.

ms-ai side​

  • knox_funnel read tool (tools/knox-funnel.tool.ts) — kinds summary | priorities | stats | contact; the source of truth for lead-state questions on funnel tenants. Honesty-gated: not_enabled → fall back to knox_stats and don't mention the funnel.
  • Action tools (tools/knox-funnel-actions.tool.ts): knox_tag_contact, knox_move_pipeline (auto), knox_trigger_workflow (confirm per workflow_trigger_mode), knox_book_meeting (hard confirm), knox_funnel_reconcile (list/apply), knox_mark_customer (→ won). All honesty-gated — ok:false means it did NOT happen. Since 37644d6a0 (2026-10-08) book/trigger/reconcile are on the chat agents too (action, analytics, generalist), not just voice.
  • knox_trigger_workflow takes a workflow id or name: NoxFunnelActionService.triggerWorkflow resolves it (case-insensitive name or exact id) against nox_funnel.pipeline_mapping.workflows; with a non-empty mapping anything unmatched returns { ok:false, reason: 'unknown_workflow', workflows: [<mapped names>] }. An empty mapping passes the value through as an id. The settings UI has no workflow-mapping editor (only PATCH writes pipeline_mapping.workflows), so in practice most tenants are on the pass-through path.
  • Brief: deterministic funnel blocks from services/knox-funnel-insights.ts (10 blocks, min-sample guards) assembled by knox-brief-snapshot.service.ts; knox_brief_offers grounds "yes, do the first one" against persisted brief_offers and executes via the mapped real tool. Conversation outcomes are classified in the fact-extraction pass (confidence ≥ 0.7) and posted to /internal/knox/funnel/conversation-outcome.
  • Math/priorities are computed in backend: NoxFunnelMathService.js (deterministic rates/velocity/bottleneck/pacing over funnel_daily_stats, rates suppressed under min-sample — never faked) and NoxFunnelPriorityService.js (explainable scoring, every component emits a human reason; no ML/LLM).

Frontend​

  • Page: views/FunnelPage.vue (route funnel, /funnel + alias /funnels, top-level in the main menu since 6e0295af; old /dashboard?tab=funnel links are forwarded by the Dashboard) wrapping views/funnel/Index.vue + views/funnel/components/ (drag-to-move FunnelBoard.vue, FunnelLayers.vue stage cards incl. Won, HotList.vue / PriorityList.vue with MarkWonButton.vue (59078a35), CallPrepPanel.vue, ReconciliationPanel.vue; stage-list search, stage drill-down StageContactsModal.vue, signal drill-down refs + call deep links, unified contact Details modal ContactDetailModal.vue — Journey / Deal (DealPanel.vue, dealChips.js) / Audit tabs).
  • Tenant settings: views/settings/nox-funnel/Index.vue (/settings/nox-funnel) — conversation-outcome toggles + chat threshold, web-visitor feeding toggle, Customer (won) mapping target, Sales calendars / Customer calendars, "When someone becomes a customer (Won)", last-scan summary, danger-zone Reset funnel (ConfirmDialog → POST …/nox-funnel/reset). Pipeline mapping is labelled after the resolved CRM (GHL, HubSpot or Salesforce); feed tags are GHL-only.
  • Card source fallback (FunnelBoard.vue sourceLabel): source: <name> until a stage reason exists; agent_k renders the agency's Agent K name.
  • Admin: Run backfill button under "Nox Funnel" in views/admin/companies/Detail.vue (422 unless the tenant switch is on; polls the background job); audit browser views/admin/nox-funnel/{AuditLogs,ContactTrace}.vue with the enable-rollout MigrationPanel on AuditLogs.