Skip to main content

Leads — Overview

Audience: Sales · Support · Management · QA · Engineering · Where in app: Monitor → Leads (/leads), Settings → Lead Scoring, Settings → Tags, Dashboard, Chats, Calls · Plan availability: All plans (B2B enrichment sources are gated — see Lead Intelligence)

A lead is a visitor whose contact info has been captured, who's engaged enough to score, or who's identified through the identity graph. Leads are captured automatically as visitors interact with the widget — no manual entry, no landing pages required. This page is the map of where leads come from, how they're categorized, what's on a lead's detail page, and how a raw anonymous visit becomes a verified, CRM-synced person.

What it does​

  • Surfaces every potential customer Knock Knock has identified, grouped by how they were captured.
  • Captures contact info automatically from chats, calls, forms, bookings, CRM landings, and B2B enrichment.
  • Lists every lead — and every Nox funnel contact — once per person on the Leads page, with funnel stage, tags, every outbound touch labelled by why it was sent (Triggered by), filters, edit/delete, bulk tag / campaign enrol, CSV export and a drawer with the score breakdown and full communication history.
  • Tracks conversions and fires hot-lead notifications when a visitor crosses the score threshold.

How it works​

Lead sources​

SourceHow
Live chatCaptured during a human chat (contact questions, AI extraction, or transfer-to-agent)
AI chatThe AI agent extracts name/email/phone naturally during conversation
Audio/video callPre-call info form, or captured during the call
AI voice callThe AI extracts contact info → saved to PersonProfile
Form interceptA first-party form submitted on the site — direct verification + identity capture
BookingThe booking flow always captures email + name (see Booking Sources)
CRM landingVisitor arrives with a hubspotutk cookie → auto-linked to the HubSpot contact
B2B enrichmentSnitcher (company) and Apollo (person), plus RB2B, turn anonymous traffic into an identified company

Lead attribution (lead_source, 2026-09-25)​

Every capture builds a lead_source snapshot (backend/app/lib/leadSource.js, PersonResolverService._buildLeadSource): lead_type (chat/call/form — a live call on the session outranks the capture surface), page_url + page_title (the page the details were given on; ms-comm stamps visitor messages with page_url/page_title from the widget and picks the message that carried the email/phone), derived product, chat_start_url/call_start_url, landing_page_url, and traffic_source (label, category, UTMs, latest gclid, referrer). URLs are origin + path only. Missing values fall back to the session's latest page view. It isn't shown in the Leads UI — it's delivered on the new_lead webhook/Zapier payload, as a "Lead source" note (+ gclid field) on GHL/HubSpot, and in the Salesforce Lead Description. See Webhooks and CRM Integration.

Form submissions that re-assert an already-captured identity update it without counting as a new lead capture (FormSubmissionService, af39e6ab4). Since a86597d4f (2026-11-14) each person_profiles.form_submissions[] entry also keeps page_url (origin + path), page_title and a readable form_name (the widget's form_intercept.js derives it from the form's label/heading/legend/button, skipping generic ids, naming embedded providers by host; FormSubmissionService.whereFilled falls back to the session's latest page view). They're returned by Nox's form lookup (with a ready filled_in sentence), the admin identity view and the lead timeline's form events — the Leads drawer doesn't render them yet.

Leads page (/leads, Leads v2 — 2026-10-21 → 2026-11-13)​

One row per person, merged from every way they became a lead — and every Nox funnel contact ("Leads = Funnels"). Backend GET /leads/:company_id (LeadsController@index, row building in app/lib/leadRows.js); frontend views/leads/index.vue + components/LeadsTable.vue, LeadDrawer.vue, LeadConversations.vue, LeadEditModal.vue, CampaignEnrollModal.vue, leadFormat.js. Main commits: backend acbf696f6 (materialized collection, edit/delete), 847865285 (lead tags), 9827ea81a (funnel stage, Triggered by, touch filters, full history, campaign enrol), 74bfe7fe0 (system tags), 19cc3f51a, fd2f0a41c, 3483c879f, 76b4d9154 (Leads v2); frontend 7b535e38, aade9d30, 6e0295af, 7f3ff19a, 8975e6ce. Menu: Monitor → Leads (gated leads.view + pages.leads).

Materialized leads collection​

LeadModel (leads, unique {company_id, key}) holds one built row per lead. _ensureBuilt rebuilds a company on read, at most every 60 s (Redis SET leads:built:<company> NX EX 60; Redis down = rebuild every read). Only a company's first load waits; later loads serve the stored rows while one in-process rebuild (per pod, inflight map) refreshes them. List, tabs, counts, filters, sort and paging are Mongo queries on leads (leadFilter + tabFilter), not in-memory filtering. The old leads:rows:<key> Redis row cache is gone; only Identified Visitors still use a 10-minute stale-while-revalidate Redis cache (cached()).

_rebuild = _leadRows (chats, calls, form profiles, Agent K deliveries, funnel contacts → buildLeadRows; unlinked form_leads as f:<id> rows, newest 5000) + attachTouches + matchLeads against the stored docs, then one unordered bulkWrite:

  • Row hash — row_hash (md5 of the built row) skips unchanged rows; with every funnel contact a lead (tens of thousands per company) rewriting them all each minute was the cost.
  • Edits survive — PUT /leads/:company_id {id, name, email, phone, company} stores only changed fields in edits.* (and re-keys the person's tags via TagService.relink). The pipeline update reads $edits.<field> before the built value, so edits win over every rebuild. matchLeads pairs a built row with the stored doc by key, else by any shared p:/s:/chat:/call:/k: token, so edits survive s: → p: re-keys and merges (merged docs' edits fold in; unmatched docs are deleted).
  • Soft delete — POST /leads/:company_id/delete {ids} (≤1000) sets deleted_at. A rebuild clears it only when last_interaction (chat/call/form/Agent K time — never a visit; funnel-only rows have none) is newer, i.e. a deleted lead returns when they get in touch again. The chats/calls themselves are untouched (the old /chat-lead-delete + /delete-lead path is no longer used by this page).
  • GDPR tombstones — rows with erased_at (from POST /leads/:company_id/erase, lib/personErasure) are never rebuilt, rewritten or deleted, and nothing sharing a token with one is rebuilt. See the GDPR docs for erase/export (/leads/:company_id/erase|export, outside companyPaused).

container.js must inject every model LeadsController reads (19cc3f51a — the page 500'd without them).

Inputs merged (_leadRows):

SourceQuery
Chatchats with lead_captured: true, lead_deleted != true
Callservice_rooms with a real contact_information.email or .phone (callLeadOr), lead_deleted != true, video_deleted != true
Formperson_profiles.form_submissions excluding form_type contact_info / pre_call; outbound_only profiles skipped
Agent Knox_actions agent: 'agent_k', status ∈ {pushed, sent} (delivered); visits matched by CRM contact (AgentKLeadVisitService) count as theirs
Funnelevery funnel_contacts doc (FUNNEL_FIELDS). Matched to a row by person → CRM id → email → phone (funnelMatcher); an unmatched contact gets its own row (p:<person> or fc:<funnel id>)

Row key: p:<person_id> when the session resolves to a person, else s:<session_id>, else chat:<id> / call:<id>. Agent K actions without a person collapse by CRM contact id → email → phone (agentKKey) into k:<action_id>-keyed rows. Funnel-only rows fc:<id>, unlinked form leads f:<id>, identified companies co:<company name>.

Contact details are tenant-owned only — chat/call contact_information, the tenant's own form fields, Agent K context.person, the funnel contact; newest non-empty value per field wins, then tenant edits. The global Person record is never read.

Derived columns (stored on the doc):

  • funnel_stage, stage_changed_at, very_warm_until (the funnel's very_warm.expires_at while active), customer (flags.customer or stage won), funnel_contact_id. The API derives stage at read time: funnel on → funnel_stage || 'none'; off → hot when intent ≥ ai_auto_trigger.threshold (default 50), else lead. hot = funnel on ? very_warm_until > now : intent ≥ threshold.
  • status — furthest of new → contacted → replied → booked from the profile and Agent K (delivery counts as contacted).
  • intent — max of every visit's lead_score.total and the funnel contact's lead_score. visits — number of visits behind the row (UI shows "— no visits" when 0 and no intent).
  • channels (UI: Traffic) — distinct source_category values; agent_k is prepended when Agent K reached them first.
  • source (UI: Source, never blank, sourceOf) — earliest of Agent K (outbound→agent_k, import, reactivation→crm_sync, knockid→identified_visitor), first chat/call/form; a first visit from AI search wins as ai_referral; else the funnel source (ghl_sync/ghl_tag→crm_sync, import, agent_k, inbound→call), else direct.
  • system_tags — lib/systemTags: Agent K's CRM tags per delivery (nextlevel agent-k-lead, signal:, source:, list:<import tag>, phone-found) + the funnel stage tag (<stage_tag_prefix><stage>, default prefix when mirroring is off) when the funnel is on. Computed from our own records, so every account sees them; test/system-tags.spec.js pins the formats to AgentKPushService / FunnelStageService.
  • contact_keys (lib/contactKeys of the shown email/phone, l:<key> when neither) — joins contact_tags (see Lead Tags).
  • crm_contact_id / crm_provider — the drawer's CRM conversation and the campaign enrol target.
  • last_activity — max of capture times, visit starts and last_reply_at; last_interaction + interaction_at[] — chat/call/form/Agent K times only (date range + undelete).

Touches and "Triggered by" (lib/touchAttribution.js, attachTouches)​

Every outbound send is stamped triggered_by: { category, name, rule_id } (on nox_actions, scheduled_nox_actions, nox_email_messages, sms_agent_messages, …). Categories: agent_k_outreach, reactivation, intent_trigger, micro_moment, nox_instructed, inbound, manual, unattributed (labels white-labelled at display time via labelFor / frontend touchAttribution.js; never stored with a brand). Rules: categoryForRule — the rule's own attribution_category wins; Agent K triggers (lead_found, email_no_visit, sequence_finished) → outreach (reactivation-only sources → reactivation); form_abandoned/chat_ended/CRM-event triggers (funnel_stage_changed, crm_stage_changed, tag_added, no_reply) → intent_trigger; fired while live → micro_moment. Campaigns: own category, else missed_call → intent_trigger, any other goal → reactivation. Drafts without a stated cause: inferForDraft (source reactivation → reactivation; Agent K sources or a sequence touch → outreach; user → manual). CRM-workflow SMS/calls on /ai-outbound/* are intent_trigger · Your CRM workflow; Simpro invoice-chase calls intent_trigger · Simpro invoice chase (fd2f0a41c).

attachTouches builds per row (365-day lookback, ≤150 touches): sent/pushed nox_actions (any agent), lifecycle opened/clicked/replied/booked events, displayed ai_auto_trigger_messages (micro-moments), chats/calls/forms (inbound) → touches[{at, channel, category, name, outcome}], last_touch; future scheduled_nox_actions (scheduled/pending_confirm) and Agent K's Mode B next follow-up (AgentKSequenceJob.gapsFor) → scheduled[], next_touch. A touch's outcome is the best lead response within 14 days or before the next touch (opened < clicked < replied < booked, else no_response). Rows match touches by person, CRM ids, sessions and phone.

Tabs (TABS; UI ids in parentheses): all, hot (label Very Warm with the funnel on, Hot Leads off), not_contacted (not-contacted), chat (chat-leads), call (call-leads), form, agent_k (agent-k), ai, the Triggered-by quick tabs reactivated / intent_triggered / micro_moment (touches.category) and agent_k_emailed (outreach + email), and identified (unchanged: user_sessions with is_identified, no person, Snitcher company, last 30 days by default, ≤5000 sessions, not counted as leads).

Query params: tab, stage (funnel stages + none, or hot/lead), status, channel, source, tag (tag ids → contact_keys), system_tag, min_intent/max_intent, search, start_date/end_date (on interaction_at), the one-touch $elemMatch group triggered_by / touch_channel / outcome / touch_from / touch_to (touch_scheduled=1 searches scheduled[] — "Tomorrow"), last_touch_from / last_touch_to / last_touch_before / last_touch_none, sort (intent | last_activity), skip/limit (limit=0 = all, CSV export), id (deep link — one row whatever the filters; chat:/call:/k: resolve to their owner). The response carries counts per tab, funnel, threshold and system_tags (distinct automatic tags in use, for the Tags filter).

Other endpoints (leadsRoutes.js, passport + companyPaused): PUT /leads/:company_id (edit), POST /leads/:company_id/delete, POST /leads/:company_id/tags {ids, add, remove} (≤1000 leads, ≤20 tags; TagService.apply), POST /leads/:company_id/campaign {campaign_id, ids? | filters?, preview} (≤5000; _matchFor reuses the page's query; Booked/Won and status: booked skipped as booked_or_won; mbx_ mailbox ids go in by email, not as CRM contacts; 403 unless campaigns_enabled). See Campaigns.

Frontend: filters (LeadFilterChip) Stage, Status, Tags (own tags + "(automatic)" system tags), Intent, Traffic, Source, Triggered by, Touch date (Today / Tomorrow (scheduled) / Yesterday / 7d / 30d / Custom range), Last touch, Channel, Outcome (hidden for Tomorrow); bulk Add tag / Remove tag / Add to campaign (campaigns_enabled) / Delete; CSV (Selected / This view / All leads) with Tags, Automatic tags, Source, last/next touch columns; LeadEditModal (vee-validate + zod). Scoring config is in Settings → Lead Scoring (/leads?tab=lead-points redirects).

Lead drawer​

components/LeadDrawer.vue, data from GET /leads/:company_id/detail?id=<row id> (LeadsController@show): score (scoreBreakdown), funnel (reason), conversation ({contact_id, lead_id, provider} for the CRM thread), crm_tags (a GHL contact's live tags via getOutreachContact, bounded 4 s; null for other CRMs — shown as "Also in your CRM") and a newest-first timeline (buildLeadTimeline): visits (source, pages with time per page, returning), chats/website calls (with started_by automation vs visitor — the auto-trigger message they answered within 30 min, and who handled it), AI phone calls (recording + transcript), emails (Agent K / Nox / mailbox; content, opens with times, click, reply folded in), SMS, WhatsApp, widget messages, forms (fields, plus page_url/page_title/form_name), bookings (calendar, rescheduled, cancelled), meeting events, notes, funnel stage changes (trigger, reason), automation fires, Agent K deliveries — each with agent, triggered_by and outcome. Chats/calls are fetched without Mongo sort/limit (sorted in JS) — with them the planner picked {company_id, created_at} and walked the company's whole history (32 s in prod).

Two tabs: Activity (the timeline, channel filter, CSV export) and Conversation (LeadConversations.vue — every chat/call/text/WhatsApp/email in full with transcript, then the CRM email/SMS thread via AgentKThread). Header actions: Edit, Delete, Erase person (GDPR) + data export (owners/agencies/super-admin, p:/s:/chat:/call:/f: ids). The open lead lives in ?lead=; ↑/↓ or j/k step rows, Esc closes.

Nox reads the same rows: the leads named query in knoxV2NamedQueries (stage, Source, touches with Triggered by, scheduled) and the "Leads refresh" path build the controller via lib/appController.

Contact information capture​

Configured via companies.contact_information_questions:

name: { enabled: bool, question_text: string }
email: { enabled: bool, question_text: string }
phone: { enabled: bool, question_text: string }

take_phone_number_before_call: true makes phone mandatory before a call can start. For AI conversations there's no hard form — the fact-extraction service pulls contact info from the transcript as the AI naturally asks "what's your name?" / "how can we reach you?".

Lead lifecycle​

Anonymous visit → engagement signals → score climbs
↓ contact captured
Identified visitor → PersonProfile created
↓ verified (form / device / CRM landing)
Verified Person → AI sees cross-session context next visit
↓ booked / converted
Conversion event → CRM sync if connected

Identity resolution (anonymous → Person → verified Person) is handled by the identity graph via VisitorIdentityService, PersonResolverService, and IdentityGraphService.

Configuration & options​

SettingWhereEffect
companies.contact_information_questionsCompany configToggle + custom prompt for name/email/phone capture
take_phone_number_before_callCompany configForce phone capture before a call
Conversion definitionCompany configWhat counts as a conversion (booking / email / phone / hot-threshold cross) (verify exact config key)
Hot-lead notification channelsNotifications settingsIn-app, Slack, email, FCM push, webhook
B2B enrichment toggles + budgetIntegrationsSee Lead Intelligence
Date filter (24h / 7 days / Custom Date)Leads UIScope every tab to a time window (start_date/end_date, whole days)
companies.ai_auto_trigger.thresholdAuto Connect agentHot-stage cut-off on the Leads page while the funnel is off (default 50)
companies.nox_funnel.enabledSettings → FunnelOn: Stage = funnel stage, Hot/Very Warm = funnel very-warm flag. See Nox Funnel
companies.campaigns_enabledSuper-admin (beta)Shows Add to campaign and allows POST /leads/:id/campaign

Conversions are configurable but typically: a booking made, email captured, phone captured, or lead score crossing the hot threshold. Tracked in the dashboard Conversions widget with per-source breakdown.

Behaviors & edge cases​

  • Anonymous visitors are not rows on the Leads page — a row needs a chat/call contact, a web form, an Agent K delivery or a funnel record; anonymous companies show only on Identified Visitors. Their score migrates to a PersonProfile once identified.
  • B2B leads have no human contact — they identify the company/network, not a specific person. Don't treat reverse-IP as a verified individual. See Lead Intelligence.
  • Same person, many sources — a visitor who chats, then books, then returns is unified onto one Person via the identity graph; the Leads page shows them as one row (p:<person_id>) and the drawer timeline merges all sources.
  • CRM landing auto-link depends on the visitor arriving with a hubspotutk cookie — direct/organic visitors won't auto-link until they identify themselves.
  • Leads go cold fast — responding within minutes materially raises conversion; the hot-lead notification fan-out exists for exactly this.

Plan & limits​

  • Core lead capture (chat/call/form/booking/CRM-landing) is available on all plans.
  • B2B enrichment (Snitcher → Apollo) is package-driven — snitcher_enabled && snitcher_allowed > 0 — and person-level identification is GDPR-gated for EEA/UK/CH visitors — see Lead Intelligence › Plan & limits.
  • CRM sync of leads requires a connected CRM (GHL / HubSpot / Salesforce / Jobber) — see CRM Integration.

Technical implementation​

  • Leads page: backend LeadsController (app/routes/leadsRoutes.js, passport + companyPaused middleware) + app/lib/leadRows.js, lib/touchAttribution.js, lib/systemTags.js, lib/contactKeys.js, LeadModel (leads); specs lead-rows, touch-attribution, touch-attribution-sources, system-tags, leads-controller-campaign. Local demo data: scripts/seed-leads-demo.js (local-only, --clean). Frontend views/leads/ (LeadsTable, LeadDrawer, LeadConversations, LeadEditModal, CampaignEnrollModal, LeadFilterChip, leadFormat.js), common/helpers/touchAttribution.js.
  • Services: backend — FormSubmissionService (form capture), FactExtractionClientService (transcript → contact facts), VisitorIdentityService / PersonResolverService / IdentityGraphService (identity), enrichment services (Rb2bService, Snitcher/Apollo; HappierLeads was deleted 2026-09-09), notification services (SlackService, FcmService, EmailQueueService), KnoxAutoEngageService (return-visit engagement).
  • Models: LeadModel (materialized Leads rows), UserSessionModel (raw session + lead_score), PersonModel (resolved identity), PersonProfileModel (enriched: name/email/company/B2B data + bookings[], form_submissions[]), TagModel / ContactTagModel (lead tags).
  • Nox tools: knox-aggregate(metric=hot_leads | missed_bookings | …), knox-stats, knox-person-lookup, knox-extracted-facts.
  • Subsystems: Identity Graph, CRM Integration.