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 id | Label | Shown when | Component | Notes |
|---|---|---|---|---|
cs_account_type | How you'll use it | self-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_brand | Agency brand | "I'm an agency" | AgencyBrandStep | "Your agency brand": logo (PNG/SVG, ≤ 5 MB) + Agency name, Continue → / Skip for now |
cs_start | Get started | always | StartStep | Name, 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_partner | Certification | cert-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_agent | Choose an agent | always | AgentStep | Widget (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_kb | Build knowledge base | any of widget/inbound/outbound | KnowledgeStep | Website (KbWebsiteSource), PDFs, text sections, FAQs; "I'll add sources later" skips |
cs_kb_review | Creating Knowledge Base for AI agents | same | KnowledgeReviewStep | One WebsiteCrawlCard per site (live scrape_progress + training state via useWebsiteCrawlProgress); primary button disabled until crawl + training land, Continue anyway after a long wait |
cs_profile | Business profile | same | ProfileStep | Basics (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_business | Your business | self-serve short path (replaces cs_start + cs_kb_review + cs_profile) and Platform API clients | BusinessStep (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_console | Test it live | widget | WidgetConsoleStep | "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_install | Install | widget | WidgetInstallStep | Snippet copy, Email this to my developer |
cs_call_agents | Inbound / Outbound / Inbound & Outbound Agent Setup | inbound and/or outbound | CallAgentsStep + CallAgentPanel | Reuses 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_k | Agent K setup | Agent K | AgentKStep | Connect 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, orcs_agent_k). Sub-accounts getcs_startfirst for their password;StartStepasks phone/timezone only for non-agency clients. - Platform API (
company.created_via === 'platform_api'):cs_start→cs_businessonly;cs_businessis 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. BackendKnoxV2InternalControllerplans['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, thencs_kb+cs_kb_review+cs_profilefor 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_atset = 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 (UNTOUCHEDmap; KEEP IN SYNC with CompanyModel +settings/widget/Index.vue, a test enforces coverage). - Triggers: CompanyModel
post('save')/pre(['updateOne','findOneAndUpdate'])hooks schedule a backgrounddetectAndApply(setImmediate, not awaited) wheneverwebsite_urlis set on a new company or actually changes (sameSitecompare — 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).KbWebsiteSourcecallsautoafter the website is added (toast "Matched your widget to your website colours"); Settings → Widget → Colors Match my website callspreviewand only fills the form.POST /playground/brand-colors { company_id, owner_key }— owner-key gated, reads only the playground's storedwebsite_url,automode (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).
SMS consent (users.sms_consent_at)
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)
| ID | Label | In progress bar? | Component | Purpose |
|---|---|---|---|---|
account | Account | Yes | steps/AccountStep.vue | Name, company name, phone, password, timezone. Skipped on load if already complete (see below). |
website | Website | Yes | steps/WebsiteStep.vue | Connect/scan the company website to seed AI knowledge. |
training | Training | No | steps/TrainingStep.vue | Trains the AI agent (driven by its own CTA, hidden from the progress bar). |
industry | Industry | Yes | steps/IndustryStep.vue | Pick the business type (uses helpers/industryTemplates.js). |
details | Details | Yes | steps/DetailsStep.vue | Business details that feed the agent's persona. |
review | Review | Yes | steps/ReviewStep.vue | "Meet {agent}. It's ready" — review the generated agent personality/flow. |
mobile-complete | Complete | No (mobile only) | steps/MobileCompleteStep.vue | Mobile success screen; hands off to desktop. |
config_widget | Customize Widget | No | ConfigurationScreen.vue | Widget appearance/layout. |
config_routing | Call Routing | No | ConfigurationScreen.vue | Call handling/routing defaults. |
config_playground | Playground | No | ConfigurationScreen.vue | Try the widget live in a sandbox. |
install | Install | No | InstallScreen.vue | Copy 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 viaPOST /email-send/<company._id>. The email body is white-label aware (omits thehello@knockknockapp.aisupport 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):
PUT /user/<id>{ onboarding_completed: true }PUT /company/<id>{ onboarding_completed: true }- Optional auto-trial: if a
registered_package_id(orlocalStorage register_pkg) resolves to a package withaffiliate_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. - Toasts "Setup complete!" and routes to
dashboard— always landing on the dashboard so users can explore.
Configuration & options
What gets written, and where:
| Step | Persisted to | Mechanism |
|---|---|---|
| Per-step completion | company.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 completion | user.onboarding_completed, company.onboarding_completed | PUT /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 opensconfig_widget. - Browser back/forward: each step
pushes a history entry (updateUrlWithStep), andindex.vuewatchesroute.query.stepto re-sync. - Mobile→desktop handoff:
mobile-completeismobileOnly. On desktop,findNextValidStepIndexskips 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_*andinstallsteps (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_completedis true, the router prevents bouncing back into/onboarding(seerouter/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 infrontend/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.
Related
- Quick Start and Platform Overview.
- Widget Installation — the snippet shown on the install step, retrievable later in Settings → Widget.
- Settings → Working Hours and Settings → Call Preferences — refine what onboarding's config steps seed.
- Free Session, Paywall & Trials — there is no auto-trial at finish; trials come only with packages that carry one.
- services/frontend · services/backend.