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
| Source | How |
|---|---|
| Live chat | Captured during a human chat (contact questions, AI extraction, or transfer-to-agent) |
| AI chat | The AI agent extracts name/email/phone naturally during conversation |
| Audio/video call | Pre-call info form, or captured during the call |
| AI voice call | The AI extracts contact info → saved to PersonProfile |
| Form intercept | A first-party form submitted on the site — direct verification + identity capture |
| Booking | The booking flow always captures email + name (see Booking Sources) |
| CRM landing | Visitor arrives with a hubspotutk cookie → auto-linked to the HubSpot contact |
| B2B enrichment | Snitcher (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 inedits.*(and re-keys the person's tags viaTagService.relink). The pipeline update reads$edits.<field>before the built value, so edits win over every rebuild.matchLeadspairs a built row with the stored doc by key, else by any sharedp:/s:/chat:/call:/k:token, so edits survives:→p:re-keys and merges (merged docs' edits fold in; unmatched docs are deleted). - Soft delete —
POST /leads/:company_id/delete {ids}(≤1000) setsdeleted_at. A rebuild clears it only whenlast_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-leadpath is no longer used by this page). - GDPR tombstones — rows with
erased_at(fromPOST /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, outsidecompanyPaused).
container.js must inject every model LeadsController reads (19cc3f51a — the page 500'd without them).
Inputs merged (_leadRows):
| Source | Query |
|---|---|
| Chat | chats with lead_captured: true, lead_deleted != true |
| Call | service_rooms with a real contact_information.email or .phone (callLeadOr), lead_deleted != true, video_deleted != true |
| Form | person_profiles.form_submissions excluding form_type contact_info / pre_call; outbound_only profiles skipped |
| Agent K | nox_actions agent: 'agent_k', status ∈ {pushed, sent} (delivered); visits matched by CRM contact (AgentKLeadVisitService) count as theirs |
| Funnel | every 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'svery_warm.expires_atwhile active),customer(flags.customeror stagewon),funnel_contact_id. The API derivesstageat read time: funnel on →funnel_stage || 'none'; off →hotwhenintent ≥ ai_auto_trigger.threshold(default 50), elselead.hot= funnel on ?very_warm_until > now:intent ≥ threshold.status— furthest ofnew → contacted → replied → bookedfrom the profile and Agent K (delivery counts as contacted).intent— max of every visit'slead_score.totaland the funnel contact'slead_score.visits— number of visits behind the row (UI shows "— no visits" when 0 and no intent).channels(UI: Traffic) — distinctsource_categoryvalues;agent_kis 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 asai_referral; else the funnel source (ghl_sync/ghl_tag→crm_sync,import,agent_k,inbound→call), elsedirect.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.jspins the formats toAgentKPushService/FunnelStageService.contact_keys(lib/contactKeysof the shown email/phone,l:<key>when neither) — joinscontact_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 andlast_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
| Setting | Where | Effect |
|---|---|---|
companies.contact_information_questions | Company config | Toggle + custom prompt for name/email/phone capture |
take_phone_number_before_call | Company config | Force phone capture before a call |
| Conversion definition | Company config | What counts as a conversion (booking / email / phone / hot-threshold cross) (verify exact config key) |
| Hot-lead notification channels | Notifications settings | In-app, Slack, email, FCM push, webhook |
| B2B enrichment toggles + budget | Integrations | See Lead Intelligence |
| Date filter (24h / 7 days / Custom Date) | Leads UI | Scope every tab to a time window (start_date/end_date, whole days) |
companies.ai_auto_trigger.threshold | Auto Connect agent | Hot-stage cut-off on the Leads page while the funnel is off (default 50) |
companies.nox_funnel.enabled | Settings → Funnel | On: Stage = funnel stage, Hot/Very Warm = funnel very-warm flag. See Nox Funnel |
companies.campaigns_enabled | Super-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
PersonProfileonce 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
hubspotutkcookie — 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 +companyPausedmiddleware) +app/lib/leadRows.js,lib/touchAttribution.js,lib/systemTags.js,lib/contactKeys.js,LeadModel(leads); specslead-rows,touch-attribution,touch-attribution-sources,system-tags,leads-controller-campaign. Local demo data:scripts/seed-leads-demo.js(local-only,--clean). Frontendviews/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.
Related
- Lead Scoring — how the score and hot threshold work
- Lead Tags · Automations · Campaigns · Re-engage
- Nox Funnel — the stages behind the Stage column
- Lead Intelligence — B2B reverse-IP enrichment
- Booking Sources — bookings as a lead source
- Live Sessions · Recorded Sessions
- Identity Graph · CRM Integration