Skip to main content

Help & Troubleshooting

Audience: Support and QA (primary), engineering (root-cause), management (escalation context) · Where in app: Help icon in the dashboard; relevant config/log screens per issue · Plan availability: All plans

Common questions and the typical answers, with the exact config field, log row, or status to check. Nox can answer most of these directly by reading the relevant field; when it can't, it should explain why and link to the right docs section.

What it does​

Provides the diagnostic checklist support uses to resolve the most common customer issues — widget visibility, identity recognition, CRM sync, AI credits, recording analysis, calls, push notifications, AI accuracy, B2B enrichment, form capture, and post-cancellation behavior.

How it works​

Each issue below lists the symptom, the likely causes, and the field/status/log to inspect. Most map to a backend config field, a recording_status, or an API request log row.

"Why does the AI know my returning visitor's name?"​

The identity graph recognized them. Either: they previously filled a form (form intercept), arrived from a HubSpot link (hubspotutk cookie matched), arrived from a GHL workflow (?contact_id=... matched), or a previous session was verified for the same device fingerprint (FingerprintJS + soft sig + IP reached the policy threshold). See Identity Graph.

"Why is the AI generic / doesn't know my returning visitor?"​

The session is claimed but not verified — the visitor typed their identity but signals didn't reach the policy threshold. Causes: their kk_user_session_id was cleared (localStorage wiped); new device + new IP + no fingerprint match scored below threshold; or the tenant is on regulated policy (score path disabled). Fix: lower the policy threshold (moderate instead of strict) or wait for a direct trigger (form, GHL/HubSpot link).

"My widget isn't showing on my site"​

Check in order:

  1. Script tag actually loaded? (Network tab — widget.js request)
  2. companies.visibility: true?
  3. companies.mobile_disable false (if testing mobile)?
  4. widget_page_rules.hide_on_pages[] matching the URL?
  5. Content-Security-Policy blocking app.knockknockapp.ai?
  6. Working hours show "offline" — the widget IS installed, just in offline mode (still functional).

"My new lead didn't sync to HubSpot"​

  • Sync is async — usually under 60s.
  • Check API Request Logs for hubspot.contact.upsert failures.
  • Token expired? Settings → Integrations → HubSpot shows status.
  • Visitor's email already a HubSpot contact with a mismatched field? The upsert key may be off.

"AI credits are draining fast"​

  • Open Billing → AI Credits Usage for a daily breakdown.
  • Voice calls eat credits fastest (~10x chat).
  • AI outbound campaigns can drain budget quickly — pause if not needed.
  • Consider response_size: "concise" on ai_chat / ai_calling.

"My recording isn't analyzed"​

Check session_files.recording_status:

  • active — visit not finished yet (waits for finalize)
  • finalized — queued for the analysis worker
  • analyzing — worker has it
  • analyzed — done; check session_analyses
  • failed / msai_handoff_failed — see error; admin can retry

Typical failures: S3 chunk missing; LLM daily cap exceeded (RECORDING_LLM_DAILY_CAP_PER_COMPANY); worker crash → retry. See Session Recording.

"Calls aren't connecting"​

  • Twilio account healthy? Admin Settings → Twilio status.
  • Working hours? Outside hours, calls fall back to a missed-call notification.
  • ai_config.call_routing: "human" + no online agents → missed call.
  • Browser blocking camera/mic? The visitor must grant permission.

"Push notifications aren't working"​

  • Device registered? Check users.fcm_tokens[].
  • OS-level "Do Not Disturb" on?
  • Browser permission for desktop granted?
  • For Electron: notifications need OS-level grant on macOS/Windows.

"AI is hallucinating about my product"​

  • Knowledge base may be sparse — add more FAQs / PDFs.
  • Page scrape may be stale — re-trigger from AI Features → Knowledge Base.
  • System prompt too loose — switch ai_chat.setting: "advanced" and tighten instructions.

"I'm not seeing companies on B2B visits"​

  • Provider enabled? rb2b_enabled / snitcher_enabled / happier_leads_config.
  • Budget remaining? lead_intelligence_allowed / rb2b_allowed.
  • Visitor's IP cloud/VPN? Reverse-IP usually can't enrich those.

"Form capture isn't catching my form"​

  • Heavily SPA-fied custom forms may need explicit support — contact support.
  • Form host on a different domain than the widget? Cross-origin iframes block by default; install the companion iframe script.
  • Form fields named in non-obvious ways (e.g. USER_INPUT for email)? Check the form's HTML.

"I cancelled my subscription but the widget is still running"​

  • Subscription is in cancelled status — service continues through expiry_date, then degrades.
  • After expiry the widget loads but AI features fall back to defaults.
  • The identity graph stops assembling context (the subscription gate trips after a ~60s cache).

"Why is Nox saying it can't answer something?"​

It probably can't (yet). Nox is honest about what's not built — use the suggested workaround.

Configuration & options​

Key fields and statuses referenced above:

Field / statusWhereMeaning
companies.visibilitybackend company docMaster widget on/off
companies.mobile_disablebackend company docHide widget on mobile
companies.widget_installedbackend company docInstall detection
widget_page_rules.hide_on_pages[]page rulesURLs to suppress the widget
session_files.recording_statusms-sessionsRecording lifecycle (see above)
ai_config.call_routingAI confighuman vs AI routing
ai_chat.setting / ai_chat.response_sizeAI configadvanced mode / concise vs detailed
ai_calling.response_sizeAI configVoice response length
users.fcm_tokens[]user docRegistered push devices
identification_provider (snitcher default / rb2b)company docWhich provider identifies visitors (admin switch)
snitcher_enabled / snitcher_allowed, rb2b_enabledcompany docB2B provider toggles + allowance
Subscription status / expiry_datesubscriptionCancellation/degradation timing
RECORDING_LLM_DAILY_CAP_PER_COMPANYenv/limitTier-2 narrative LLM daily cap

Behaviors & edge cases​

  • HubSpot/CRM sync is async (~under 60s) — a missing lead immediately after capture is usually just lag.
  • Reverse-IP enrichment cannot resolve cloud/VPN IPs.
  • Cross-origin forms are blocked by default and need the companion iframe script.
  • Post-cancellation degradation is delayed by a ~60s cache on the subscription gate.
  • "Claimed" vs "verified" is the core identity distinction behind most "AI doesn't know my visitor" tickets.

Plan & limits​

All troubleshooting applies on all plans. B2B enrichment and live-session features are budget/add-on gated (snitcher_allowed, rb2b_enabled) — verify exact allowances against current package config.

Technical implementation​

How to reach support​

  • Help & Support (/support) — create a ticket ("Suggestion", "Bug Report", "Question", "Other") with up to 5 screenshots (add, paste or "Take screenshot"); tickets get a KK-n number, a status ("We're looking into it", "Waiting for your reply", "Fix in progress", "Resolved") and a public status link (/t/:number?token=…), and replies happen by email. Agencies have their own form at /agency/support (optionally on behalf of a client). The menu items are hidden for now (navVisibility.js SHOW_SUPPORT_NAV = false; ?test_support shows them) — the routes work if linked directly.
  • Nox opens a ticket itself when something needs a person (billing dispute, refund, account deletion) and quotes the ticket number — unless it goes to the agency.
  • Email support (the support mailbox becomes tickets only where SUPPORT_IMAP_HOST is configured).
  • For agency-managed accounts: with Agency client tickets on (Admin → Settings → Feature Flags) and the agency answering its clients, the client's tickets and Nox hand-offs go to the agency's Client tickets inbox; the agency can escalate to us with Send to Knock Knock.

Support works the tickets in the ops workspace.