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
| Stage | How it's earned |
|---|---|
cold | entered the funnel (Agent K push, feed tag, form, opportunity seed) |
intermediate | first visit/open/click, opens ≥ email_open_threshold (3), answered call, reply, chat, score_bands.intermediate |
warm | visits ≥ 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) |
booked | a 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) |
won | terminal — 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)
| Collection | Model | Notes |
|---|---|---|
funnel_contacts | app/models/FunnelContactModel.js | one 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_logs | NoxFunnelAuditLogModel.js | every decision (dedupes, gates, flips, intercepts) — TTL 120 days (live deployments need a manual collMod) |
funnel_daily_stats | FunnelDailyStatsModel.js | per (company, local day) census/transitions/dwell — the math engine's input |
funnel_reconciliation_items | NoxFunnelReconItemModel.js | behaviour stage vs CRM layer mismatches, deduped review queue |
brief_offers | BriefOfferModel.js | executable brief offers, valid_until ≈ 48h (read-time gate, no TTL delete) |
lead_lifecycle_events | LeadLifecycleEventModel.js | append-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)
| Job | Schedule | Does |
|---|---|---|
FunnelSweepJob | every 10 min | folds 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) |
FunnelDailyStatsJob | hourly (once per local day) | yesterday's census rollup into funnel_daily_stats |
KnoxGhlSyncJob | 03:00 UTC | (pre-existing) GHL sync the funnel jobs depend on |
FunnelDormancyJob | 04:00 UTC | step-down demotion, very-warm hold expiry, reactivation flagging |
NoxFunnelReconcileJob | 04:30 UTC | mapped-pipeline scan → recon queue; feed-tag scan; closed-won/lost polling |
FunnelBackfillJob | 05: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 |
FunnelFirstImportJob | hourly at :20 | paces 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 |
NoxFunnelLearningJob | Mon 05:00 UTC | demote-only self-learning: repeated rejections (n≥5, ≥60%) raise a threshold one notch into nox_funnel.learned |
DailyBriefEmailJob | every 10 min tick | sends 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_rulestag enter at that stage (upward-only against an earned stage); legacy flatfeeding.tagsreads 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 reconcileadd_tagand the move fallback write through it. Sincede910324bthe write adds before it removes (the old order left a contact with no stage tag when the add failed) and stampsfunnel_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 withtag_synced_stage != stage(unindexed$exprscan), excluding companies whosenox_funnel.stage_tag_prefixis 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 gotnextlevel 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 havetag_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 dropsflags.customer. - Pipeline mapping —
pipeline_mappingmaps GHL pipeline/stage → funnel layer; the reconcile job compares behaviour stage vs mapped location and queues mismatches for owner approval (knox_funnel_reconcilein chat, or the dashboard Reconciliation panel).movePipelinefalls 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 —
withGhlBackoffonsearchOpportunities(a swallowed 429 read as a short page and silently truncated the board scan), stage-tag sync writes, andhydrateIdentity.getContact; HighLevel SDK clients uselogLevel '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_idand deletes the funnel doc only when cold with zero signals; auditedghl_deleted_cleanup. - Backfill fixes — seeds only Agent-K-pushed kk_tokens:
source $nin ['ghl_backfill', 'manyreach'](de910324b). The kk-token backfill and thesaveContacthook stamp aghl_backfilltoken on the tenant's entire CRM, so seeding every token with a contact id imported whole address books labelledagent_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_hydrateUnnamedrepairs 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.:idis 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 + clearslearned; audit logs kept, incl. afunnel_resetrow; 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) sortlast_engagement_at, updated_at, _id— without the_idtiebreak cold contacts (null engagement,updated_atmoving under the cursor) repeated across pages.FunnelBoard.vuealso dedupes on append and pages off the server's page count, notitems.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_funnelread tool (tools/knox-funnel.tool.ts) — kindssummary | priorities | stats | contact; the source of truth for lead-state questions on funnel tenants. Honesty-gated:not_enabled→ fall back toknox_statsand don't mention the funnel.- Action tools (
tools/knox-funnel-actions.tool.ts):knox_tag_contact,knox_move_pipeline(auto),knox_trigger_workflow(confirm perworkflow_trigger_mode),knox_book_meeting(hard confirm),knox_funnel_reconcile(list/apply),knox_mark_customer(→ won). All honesty-gated —ok:falsemeans it did NOT happen. Since37644d6a0(2026-10-08) book/trigger/reconcile are on the chat agents too (action, analytics, generalist), not just voice. knox_trigger_workflowtakes a workflow id or name:NoxFunnelActionService.triggerWorkflowresolves it (case-insensitive name or exact id) againstnox_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 (onlyPATCHwritespipeline_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 byknox-brief-snapshot.service.ts;knox_brief_offersgrounds "yes, do the first one" against persistedbrief_offersand 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 overfunnel_daily_stats, rates suppressed under min-sample — never faked) andNoxFunnelPriorityService.js(explainable scoring, every component emits a human reason; no ML/LLM).
Frontend
- Page:
views/FunnelPage.vue(routefunnel,/funnel+ alias/funnels, top-level in the main menu since6e0295af; old/dashboard?tab=funnellinks are forwarded by the Dashboard) wrappingviews/funnel/Index.vue+views/funnel/components/(drag-to-moveFunnelBoard.vue,FunnelLayers.vuestage cards incl. Won,HotList.vue/PriorityList.vuewithMarkWonButton.vue(59078a35),CallPrepPanel.vue,ReconciliationPanel.vue; stage-list search, stage drill-downStageContactsModal.vue, signal drill-down refs + call deep links, unified contact Details modalContactDetailModal.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.vuesourceLabel):source: <name>until a stage reason exists;agent_krenders 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 browserviews/admin/nox-funnel/{AuditLogs,ContactTrace}.vuewith the enable-rollout MigrationPanel on AuditLogs.