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 / status	Where	Meaning
companies.visibility	backend company doc	Master widget on/off
companies.mobile_disable	backend company doc	Hide widget on mobile
companies.widget_installed	backend company doc	Install detection
widget_page_rules.hide_on_pages[]	page rules	URLs to suppress the widget
session_files.recording_status	ms-sessions	Recording lifecycle (see above)
ai_config.call_routing	AI config	human vs AI routing
ai_chat.setting / ai_chat.response_size	AI config	advanced mode / concise vs detailed
ai_calling.response_size	AI config	Voice response length
users.fcm_tokens[]	user doc	Registered push devices
rb2b_enabled / snitcher_enabled / happier_leads_config	enrichment config	B2B provider toggles
lead_intelligence_allowed / rb2b_allowed	budgets	Enrichment budget gates
Subscription status / expiry_date	subscription	Cancellation/degradation timing
RECORDING_LLM_DAILY_CAP_PER_COMPANY	env/limit	Tier-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 (lead_intelligence_allowed, rb2b_allowed) — verify exact allowances against current package config.

Technical implementation

• Widget visibility / company config: backend, widget.
• Recording lifecycle and analysis worker: ms-sessions, Session Recording.
• Calls (Twilio/ElevenLabs/Ultravox): ms-communication.
• AI credits, agent settings, hallucination fixes: ms-ai, Knowledge Base RAG.
• Identity recognition (claimed vs verified, policies): Identity Graph.
• CRM sync + API request logs: CRM Integration.

How to reach support

• Help inside the dashboard (Help icon).
• Email support.
• For agency-managed accounts: contact the managing agency first.

Related

• Platform Overview · Dashboard · Quick Start · Glossary