Skip to main content

New-Company Onboarding

Audience: Sales · Support · QA · Engineering · Management · Where in app: /setup (route client-setup); legacy /onboarding · Plan availability: All plans (runs before/around subscription)

Every new web owner — self-serve signups and agency-invited clients — is forced through client setup at /setup (views/client-setup/, store store/clientSetup.js, c6404f04 2026-09-15 onward) before reaching the dashboard. The client picks which agents to set up, and the flow builds a per-agent path: shared knowledge base + business profile once, then the widget test console and install, call-agent setup, and Agent K. The older /onboarding wizard (below) now only serves accounts that were already part-way through it.

Routing (router/onboardingTarget.js)​

Web owners with user.onboarding_completed false are redirected by router/index.js. onboardingTarget(company): agency client (agency_id) → client-setup; company whose onboarding_steps hold only old (non-cs_) ids → onboarding; everything else → client-setup. Sticky: once any cs_ id is recorded the account stays on /setup. Agency-invited clients arrive via /invite/:inviteKey (InviteView) → /setup.

Client setup (/setup)​

Step ids carry a cs_ prefix and are persisted exactly like the old wizard — POST /company/complete-onboarding-step pushes them onto company.onboarding_steps, step data goes through PUT /company/:id. ?step=<id> deep links are honoured only into ground already covered (never skip ahead); with none, the flow resumes at the first incomplete step in the plan (or the last step if all are done but finish was never pressed). The chosen agents are kept per company in localStorage (kk_client_setup_agents:<company_id>) so a reload resumes the same plan.

Step idLabelShown whenComponentNotes
cs_account_typeHow you'll use itself-serve signups, and agency sub-accounts without the "Who is this for?" question (never partners)AccountTypeStep"Let's set you up": goal cards (Website visitors / Answering calls / Making calls / Finding new customers → widget / inbound / outbound / agentK; the first by FIRST_AGENT_ORDER widget → inbound → agentK → outbound is set up in-flow), Your website, Who is this for? (My own business / I'm an agency; AppSumo tiers show only what allow_agency permits). Read my website → / "No website? Upload a PDF instead" ("I'll add my website later" when the agency default KB gives content). Creates the company (POST /user/company, for_agency: true on the agency answer) then, for agency, convertOwnSiteToAgency → POST /agencies/self-serve (Agency overview)
cs_agency_brandAgency brand"I'm an agency"AgencyBrandStep"Your agency brand": logo (PNG/SVG, ≤ 5 MB) + Agency name, Continue → / Skip for now
cs_startGet startedalwaysStartStepName, business name; self-serve also phone + timezone (only if still Pacific/Auckland while the browser differs); password fields only when !is_password_set && !social_login (8+ chars, upper/lower/number); SMS consent — required for agency clients, shown to self-serve only if sms_consent_at is unset; ticking stamps users.sms_consent_at. Auto-complete when accountReady
cs_partnerCertificationcert-invite signups with unanswered programme questions (GET /certification/me → profile.required, 5s timeout fail-open)PartnerStep"About your certification"; stays in the plan once answered
cs_agentChoose an agentalwaysAgentStepWidget (always), Inbound (ai_inbound_call_allowed), Outbound (ai_outbound_call_allowed), Agent K (selfServe: needs a non-empty wallet — POST /company/agent-k/onboarding-enable → 402 WALLET_EMPTY "Add funds to your wallet to enable Agent K."; grants nothing, Agent K is on for every company); "Set up all of them"
cs_kbBuild knowledge baseany of widget/inbound/outboundKnowledgeStepWebsite (KbWebsiteSource), PDFs, text sections, FAQs; "I'll add sources later" skips
cs_kb_reviewCreating Knowledge Base for AI agentssameKnowledgeReviewStepOne WebsiteCrawlCard per site (live scrape_progress + training state via useWebsiteCrawlProgress); primary button disabled until crawl + training land, Continue anyway after a long wait
cs_profileBusiness profilesameProfileStepBasics (agent name, company, industry, offering) → Details (one-sentence description, hours, goal, escalation contact); generates the agent prompts. The description is prefilled from the website on mount (see below)
cs_businessYour businessself-serve short path (replaces cs_start + cs_kb_review + cs_profile) and Platform API clientsBusinessStep (f6e98967, ee8363e4)Watches the crawl ("Reading your website"), then "Here's what we found": Business name, Industry (+ optional trade), "What you do, in one sentence", Hours, Time zone, Agent name (optional; placeholder = brand assistant name, maxlength 40), "What should <agent> do?" chips (Book meetings / Capture leads / Answer questions / Send quotes). No phone field. Looks right — continue. For created_via: 'platform_api' it fills itself and saves unseen (see below)
cs_widget_consoleTest it livewidgetWidgetConsoleStep"Try it live": AI Model (same list Settings offers), Voice, Language, editable chat / voice (S2S) prompt cards, Apply & refresh preview, SimpleTestConsole against the real agent
cs_widget_installInstallwidgetWidgetInstallStepSnippet copy, Email this to my developer
cs_call_agentsInbound / Outbound / Inbound & Outbound Agent Setupinbound and/or outboundCallAgentsStep + CallAgentPanelReuses the settings tab components (phone, AI engine, behaviour; inbound also forwarding, screening, hours). Skip to dashboard (top bar) finishes onboarding but leaves cs_call_agents incomplete so the dashboard cards still flag it
cs_agent_kAgent K setupAgent KAgentKStepConnect LeadConnector first (install with return_path: '/setup'), pick the sub-account, then the embedded Agent K wizard; skippable

Paths (store/clientSetup.js plan):

  • Self-serve (isSelfServe: own signups, the agency's own site after "I'm an agency", and agency sub-accounts — not partners): [cs_start (sub-accounts only)], cs_account_type, [cs_agency_brand], [cs_agent, cs_kb only while still pending], cs_business, then the first agent's steps (cs_widget_console + cs_widget_install, cs_call_agents, or cs_agent_k). Sub-accounts get cs_start first for their password; StartStep asks phone/timezone only for non-agency clients.
  • Platform API (company.created_via === 'platform_api'): cs_start → cs_business only; cs_business is hidden from the progress count. It waits up to ~1 min for default-KB PDFs, writes the description with AI (fallback: the agency default description), saves, and finishes on the dashboard — no agent choice, test console or install. Backend KnoxV2InternalController plans ['cs_start','cs_business',…goals] for Nox.
  • Long path (certification partners, and sub-accounts already part-way through it): cs_start, [cs_partner], cs_agent, then cs_kb + cs_kb_review + cs_profile for widget/inbound/outbound, then the agent steps. Before any choice the longest widget path is shown so the progress bar is honest; Agent K alone skips the KB/profile steps.

AppSumo accounts can't pick Agent K (company.agent_k_blocked).

Finish (clientSetup.finish()): PUT /user/:id + PUT /company/:id { onboarding_completed: true }, autoSubscribeRegisteredPackage (self-serve card-free trial / $0 package, idempotent), then the dashboard — or, after an "I'm an agency" signup, finishAgencySignup signs in as the agency (stored token, else linked-account switchPortal, else loginAs) and opens agency-portal-setup?step=plan; or, when an agency ran this from /agency-setup (agencyPortalHandoff), restore the agency session and go back there (Back to portal setup). The dashboard then shows ClientSetupCards ("Set up your agents" / "You're live", per-agent Set up / Manage) for anyone who onboarded through /setup and for every agency client.

Onboarding quick crawl without credits (9a557ed18)​

Self-serve signups now have the $10 welcome wallet while onboarding (Wallet); for those without it (older signups, an empty wallet), CompanyWebsiteController.scrape lets an eligible company (!agency_id && !onboarding_completed) run a quick crawl anyway: quick_links capped at 11 (homepage + 10 AI-picked pages), at most 3 tries per company, counted in companies.onboarding_quick_crawls via a conditional $inc claim (released if the enqueue fails). Full crawls and agency clients still get the no-credits refusal. KbWebsiteSource falls back to this on a 402.

Brand colours from the website (4570774e2, 2026-10-08)​

backend/app/lib/brandColors.js reads the site (SSRF-guarded via lib/ssrfGuard.js; 8 s page / 5 s asset timeouts, up to 4 stylesheets) and picks a primary + distinct secondary: <meta name="theme-color"> → manifest theme_color → brand-named CSS vars (--primary, --brand, --wp--preset--color--primary…) → weighted button/link colours; greys/near-white/near-black never count. buildWidgetColors maps them onto every widget type's colour paths (primary_color, extended_widget_colors, smart/mini/pill/welcome colours, footer + bubble backgrounds) with black/white text via contrast.

  • Stored: companies.brand_colors { primary, secondary, source_url, applied_at }. applied_at set = applied once; auto mode never applies again.
  • Never over a choice: colorsUntouched(company) must be true — every path auto-apply writes must still be a schema/Settings default (UNTOUCHED map; KEEP IN SYNC with CompanyModel + settings/widget/Index.vue, a test enforces coverage).
  • Triggers: CompanyModel post('save') / pre(['updateOne','findOneAndUpdate']) hooks schedule a background detectAndApply (setImmediate, not awaited) whenever website_url is set on a new company or actually changes (sameSite compare — an unchanged URL resent by Settings → Organization doesn't count, so no silent backfill). Covers signup, /setup, agency-created clients, platform API, admin, playgrounds.
  • Endpoints: POST /company/brand-colors { mode: 'auto' | 'preview', website_url?, company_id? (admin) } — always 200 { detected, applied, reason?, colors?, company? } (reasons: no_website, already_applied, colors_customised, no_colors_found, error). KbWebsiteSource calls auto after the website is added (toast "Matched your widget to your website colours"); Settings → Widget → Colors Match my website calls preview and only fills the form. POST /playground/brand-colors { company_id, owner_key } — owner-key gated, reads only the playground's stored website_url, auto mode (agency playground defaults count as a choice).

One-sentence description from the website (d42fbc5ee, ms-ai 15256f31d)​

ProfileStep calls POST /company/website-description { website_url } on mount when the description is empty and the company has a website_url; shows "Reading your website…" then "Filled in from your website — edit it if it's not quite right." Never overwrites typed text; nothing is saved server-side. Backend lib/websiteDescription.js fetches the homepage (shared SSRF-guarded fetchPage) and asks ms-ai POST /business-description { company_id, company_name, page_text } (forwards the caller's JWT; 15 s timeout; DEFAULT_CHAT_MODEL, ≤ 200 chars, '' on failure); fallback = og:description / meta description, then title + main heading. Every failure → { description: '' }.

Deferred company on self-serve signup (ee0dff872, 2026-10-13)​

Register sends defer_company: true from the web app (not desktop/older clients, not cert invites): no company is created at signup — the business details are kept on users.pending_company and AccountTypeStep creates the company via POST /user/company (AuthController.createPendingCompany → createSignupCompany: default greeting video + "General" chatbot + the $10 welcome wallet unless for_agency; clears pending_company). Since 05e656c5 the agency answer creates it too and converts it into the agency's own site. The Register form now asks only name, work email and password (business name and phone moved out; SignupPreview.vue beside it); agency-invite registration keeps Agency Name, Confirm Password and SMS consent. Login tolerates a web owner with pending_company and no company yet.

Website preview proxy (GET /proxy/website)​

The live preview in the playground / onboarding config screen (PlaygroundPreview.vue, ConfigurationScreen.vue, useSimplePlayground.js) frames the tenant's site through backend/app/routes/CompanyRoutes.js /proxy/website (screenshot fallback /proxy/website/screenshot when the page reports itself blocked). Injected scripts: <base> + PREVIEW_LINK_SCRIPT, plus since 2026-10-01 PREVIEW_HISTORY_SCRIPT — SPA routers (Next.js App Router) call history.replaceState/pushState with a relative URL that resolves against the target origin and throws SecurityError; the wrapper re-points only such URLs at our origin. Also: a target URL ending in a file (…/index.html) no longer gets a trailing slash (assets 404'd), and GoDaddy Website Builder's /markup/ad fetch failure is ignored instead of flagging the page as blocked (test/website-proxy.spec.js).

Register shows two consent boxes (transactional + marketing, at least one required) except on white-label domains; only the transactional one is stored — registration (AuthController, /user/register · /users/register) with sms_consent: true stamps sms_consent_at. StartStep asks again only when it's missing (and always for agency clients).

Legacy wizard (/onboarding)​

Only accounts that recorded old (non-cs_) step ids still land here. Everything from this heading down to Plan & limits describes that wizard.

The wizard shell is onboarding/index.vue; step order and visibility live in the Pinia store store/onboarding.js (ALL_ONBOARDING_STEPS). The current step is derived from ?step=<n> in the URL, kept in sync via browser back/forward.

Steps (in order)​

IDLabelIn progress bar?ComponentPurpose
accountAccountYessteps/AccountStep.vueName, company name, phone, password, timezone. Skipped on load if already complete (see below).
websiteWebsiteYessteps/WebsiteStep.vueConnect/scan the company website to seed AI knowledge.
trainingTrainingNosteps/TrainingStep.vueTrains the AI agent (driven by its own CTA, hidden from the progress bar).
industryIndustryYessteps/IndustryStep.vuePick the business type (uses helpers/industryTemplates.js).
detailsDetailsYessteps/DetailsStep.vueBusiness details that feed the agent's persona.
reviewReviewYessteps/ReviewStep.vue"Meet {agent}. It's ready" — review the generated agent personality/flow.
mobile-completeCompleteNo (mobile only)steps/MobileCompleteStep.vueMobile success screen; hands off to desktop.
config_widgetCustomize WidgetNoConfigurationScreen.vueWidget appearance/layout.
config_routingCall RoutingNoConfigurationScreen.vueCall handling/routing defaults.
config_playgroundPlaygroundNoConfigurationScreen.vueTry the widget live in a sandbox.
installInstallNoInstallScreen.vueCopy the widget snippet / email it to a developer; finish.

The three config_* steps share one component (ConfigurationScreen.vue); it derives which section to render from the current step ID, and the same component reference is reused across the three keys so Vue keeps it mounted between them (no re-mount flicker).

Progress bar vs hidden steps​

The horizontal stepper only shows steps with showInProgressBar: true (progressBarSteps): Account, Website, Industry, Details, Review. training, all config_*, install, and mobile-complete are hidden and driven by their own screens' CTAs.

Account-step skip​

On load, the store snapshots whether account info is already complete (captureAccountStepState). "Complete" means: first name, company name, phone number, a set password (or social login), and the company timezone is not still the backend default (Pacific/Auckland) when the user's system timezone differs. If complete at load, the account step is removed from activeSteps for the whole session (the snapshot prevents the step from vanishing mid-session after the user saves it).

Install screen​

InstallScreen.vue shows the embed snippet:

<script>
// Knock Knock Widget
window.company_id = '<company._id>'
var newScript = document.createElement('script')
newScript.src = '<API_URL>/widget/widget.js'
document.getElementsByTagName('HEAD')[0].appendChild(newScript)
</script>

From here the user can:

  • Copy Code to the clipboard.
  • Email to Developer — opens a modal, collects developer emails (FormMultipleEmails), and posts the install email via POST /email-send/<company._id>. The email body is white-label aware (omits the hello@knockknockapp.ai support line for white-labeled companies).
  • Email Me Setup Link (mobile) — sends the same instructions to the signed-in user so they can continue on desktop; shows a "what to do next" magic-link modal.
  • Go to Dashboard — calls finishOnboarding().

It notes the snippet can always be retrieved later under Settings → Widget → Installation.

Finishing​

finishOnboarding() (store):

  1. PUT /user/<id> { onboarding_completed: true }
  2. PUT /company/<id> { onboarding_completed: true }
  3. Optional auto-trial: if a registered_package_id (or localStorage register_pkg) resolves to a package with affiliate_program && trial_without_card && free_trial === 'yes', it creates a trial subscription (POST /subscription, trial: true), reloads the subscription + company, and clears the local register keys.
  4. Toasts "Setup complete!" and routes to dashboard — always landing on the dashboard so users can explore.

Configuration & options​

What gets written, and where:

StepPersisted toMechanism
Per-step completioncompany.onboarding_steps[]POST /company/complete-onboarding-step (completeStep)
Step data (account/industry/details/config)company.*PUT /company/<id> with the step payload, then complete-onboarding-step
Final completionuser.onboarding_completed, company.onboarding_completedPUT /user/<id>, PUT /company/<id>
Install email(email only — no DB write)POST /email-send/<company._id>

skipStep(stepId) marks a step complete with an empty payload (no data saved) — used where a step can be passed without input.

Behaviors & edge cases​

  • Resume after leaving: with no ?step, the store resumes at the step after the last completed one; if everything is complete it opens config_widget.
  • Browser back/forward: each step pushes a history entry (updateUrlWithStep), and index.vue watches route.query.step to re-sync.
  • Mobile→desktop handoff: mobile-complete is mobileOnly. On desktop, findNextValidStepIndex skips it; on mobile it's shown and routes users to email themselves the desktop magic link.
  • Theme + logout are available in the onboarding header; the header/progress bar are hidden on the full-viewport config_* and install steps (showInProgressBar === false).
  • White-label branding: logo, name, store links, and email copy resolve through useAppBranding / appStore.brandingName (agency name first). White-labeled flows must not surface the Knock Knock support address.
  • Router exit guard: once user.onboarding_completed is true, the router prevents bouncing back into /onboarding (see router/index.js).

Plan & limits​

Onboarding runs for all new web-owner accounts regardless of plan. The only plan-adjacent behavior is the auto-trial branch in finishOnboarding (affiliate packages with card-free trials). Exact package eligibility is data-driven (the package record's affiliate_program/trial_without_card/free_trial flags) — confirm specifics with billing/product (verify).

Technical implementation​

  • Shell view: frontend/src/views/onboarding/index.vue
  • Client setup: frontend/src/views/client-setup/{index.vue,steps/*,components/*}, store/clientSetup.js, router/onboardingTarget.js, components/ClientSetupCards.vue
  • Legacy step components: frontend/src/views/onboarding/steps/* (Account, Website, Training, Industry, Details, Review, MobileComplete)
  • Shared config screen: frontend/src/views/onboarding/ConfigurationScreen.vue
  • Install screen: frontend/src/views/onboarding/InstallScreen.vue
  • Supporting components: onboarding/components/* (Playground*, StepNavigation, DynamicField, MobileStepHeader)
  • Helpers: onboarding/helpers/industryTemplates.js, masterVoiceTemplate.js
  • Store: frontend/src/store/onboarding.js (ALL_ONBOARDING_STEPS, completeStep, skipStep, finishOnboarding, URL sync)
  • Route: name onboarding, path /onboarding (auth required, onboarding check skipped); redirect logic in frontend/src/router/index.js
  • Backend: POST /company/complete-onboarding-step, PUT /company/<id>, PUT /user/<id>, POST /subscription, POST /email-send/<id>, POST /company/agent-k/onboarding-enable, POST /agencies/self-serve, POST /company/brand-colors, POST /company/website-description, POST /company-websites/:id/scrape (onboarding quick crawl). See services/backend.