Skip to main content

White-Label

Audience: Sales / Agency-success / Management (engineers for the technical section) · Where in app: Agency → Settings / White-Label Domains · Plan availability: Agency / Enterprise tier (widget-footer-only may be plan-gated for direct customers)

White-label re-brands Knock Knock under an agency's identity across several independent surfaces: the widget footer, a custom portal domain, a custom widget domain, branding (name/logo/colors), the Nox assistant name, transactional emails, and the desktop installer. Each can be enabled independently.

What it does​

Lets clients experience the platform as the agency's own product:

  • Replace "Powered by Knock Knock" in the widget footer.
  • Serve the admin portal and the widget from the agency's own domains.
  • Apply the agency name, logo, and theme colors throughout.
  • Rename the in-app Nox assistant.
  • Brand transactional emails.
  • Ship a branded desktop installer.

How it works​

Branding values live on the AgencyModel (name, logo_file, theme_colors, nox_name, reply_email). Custom domains are registered as AgencyDomainModel rows; the agency adds DNS records at their registrar, the platform validates them (certificate + DNS), and once active the domain routes to the agency's white-labeled portal. A public branding endpoint (/agency-domains/branding/:domain) returns the name, logo, theme, and Nox name so the frontend can render the agency's look before login. The desktop app's white-label is a separate build-time flag (see Desktop App).

Configuration & options​

Replaces "Powered by Knock Knock" on the embedded widget. On companies.widget_whitelabel:

FieldWhat
is_enableTurn the custom footer on
texte.g. "Powered by YourBrand"
urlLink target

Per-domain overrides are supported for agencies serving many client domains (the widget reads the current host and picks the matching brand).

2. Custom portal domain (AgencyDomainModel)​

Serves the admin dashboard from e.g. app.youragency.com.

  1. Agency adds the domain in Agency → White-Label Domains (POST /agency-domains). Agency staff can add domains too (the controller resolves the agency via getAgency, which handles agency_staff); the add-domain form validates the domain client-side.
  2. The platform requests a certificate and returns DNS validation records (dns[]: key ownership/dns, type, name host-only CNAME, value, status pending→active).
  3. Agency adds the CNAME(s) at their registrar (host-only format works across providers).
  4. A periodic job checks validation; status flips to active (GET /agency-domains/:id/check-status).
  5. The portal serves with agency branding (logo, colors, name, Nox name).

Cookie scope is per-domain, so sessions don't leak between agencies.

3. Custom widget domain​

Serves the embeddable widget from e.g. widget.youragency.com so visitors see only the agency's domain in page source / network requests. Same DNS/CNAME pattern; configured per company.

4. Branding (name / logo / colors / Nox name)​

In Agency → Settings:

  • Agency Name — appears on login, sidebar, emails, anywhere the platform name would.
  • Logo — AgencyModel.logo_file.
  • Theme colors — theme_colors: primary, secondary, accent, sidebar bg/text, header bg/text.
  • Assistant name — nox_name renames Nox everywhere clients see it (assistant button/panel, replies, Daily Brief email, API/CRM references). Applies to all companies under the agency. Frontend resolution: useAppBranding.js (domain branding → logged-in agency store branding → defaults).
  • Assistant voice — AgencyModel.nox_voice_id: agency-picked ElevenLabs voice for Nox voice mode, applied as a per-session TTS override on the shared agent (ms-ai).
  • Reply Email — sender for automated agency emails.

5. Email branding​

All company-facing system emails are branded (2026-07): a shared backend/app/views/templates/_header-logo.html partial swaps the header icon to the agency logo on a white chip (original icon otherwise), applied across every template including hero-style chat-transcript / daily-recap; footer carries the agency chip. GeneralHelper.app_name(company_id) resolves the product name — gated on company.agency_id: no agency → "Knock Knock", else the agency's name. Sends must pass company_id or white-label resolution never runs (past bugs: BookingController / SubscriptionController omitted it).

Verified-domain links only: email links use the agency's custom portal domain only when the domain has every DNS record status: 'active' (GeneralHelper.getActiveAgencyDomain — dns.every(e => e.status === 'active')), otherwise the shared domain.

6. Desktop app white-label​

A build-time flag (WHITE_LABEL=true → __WHITE_LABEL__) produces a branded installer — app name, bundle id, icon, menu links, and update feed all change. Current target brand: Next Level AI (com.nextlevelai.app). Built via npm run build:next / publish:next. See Desktop App.

7. Installable PWA (per-tenant manifest)​

The web app is an installable PWA with a per-tenant manifest — name/icon follow the resolved branding (agency logo/name on white-label domains, Knock Knock defaults otherwise), with a standalone-mode title fix. Implemented in frontend/src/App.vue + public/sw.js (commit be0bcc81).

Behaviors & edge cases​

  • "My custom domain isn't loading" (QA/support): confirm the CNAME points to the documented edge target; TLS provisioning can take a few minutes (DNS up to ~48h to fully propagate); make sure the CNAME isn't proxied behind Cloudflare; check the domain's status is active via check-status.
  • White-label hides the brand, not the implementation: DevTools users can still see Knock Knock API endpoints.
  • Fixed callback domains: some Stripe webhooks and OAuth redirects use a fixed knockknockapp.ai domain — agencies should disclose this (typically via a DPA).
  • Email deliverability: DKIM/SPF depend on the agency providing their own domain authentication for outbound email.
  • What stays Knock Knock even when fully white-labeled: Stripe receipts (charged via the underlying Stripe account), AI-provider cost attribution (Anthropic/OpenAI/ElevenLabs), and Knock Knock as the underlying data processor.
  • Single-company white-label for direct customers: widget-footer-only white-label may be plan-gated (Pro+); full white-label (portal/widget domains, desktop installer) is agency-only.

Plan & limits​

  • Full white-label is an agency/Enterprise capability.
  • Widget-footer-only branding for direct (non-agency) customers is plan-gated — verify which tier.
  • The desktop white-label brand is currently Next Level AI — verify if additional agency desktop brands are provisioned.

Technical implementation​

  • Models: AgencyModel (name, logo_file, theme_colors, nox_name, nox_voice_id, reply_email), AgencyDomainModel (domain, certificate ref, dns[]), companies.widget_whitelabel.
  • Controller/routes: AgencyDomainController (/agency-domains*, public /agency-domains/branding/:domain and /agency/branding/:agency_id); branding edited via AgencyController (PUT /agencies/:id).
  • Frontend: frontend/src/views/agency/WhiteLabelDomains.vue, Settings.vue.
  • Desktop: build-time flag — see /services/desktop and Desktop App.
  • See Agency Overview and backend service.