Skip to main content

Organization Settings

Audience: Support / Management (engineers for the technical section) · Where in app: Sidebar → Settings → Organization · Plan availability: All plans

Organization settings are the company-level config that owns most defaults across the platform. Almost everything here lives on the companies document (CompanyModel). Changing a value here generally takes effect on the next request — there's no redeploy.

What it does​

Defines who the company is and how the widget and AI behave by default:

  • Company profile (name, website, industry, timezone).
  • Branding (logo, email signature/footer where the plan allows).
  • Working hours and timezone (drive widget online/offline state).
  • Widget visibility controls (global on/off, mobile).
  • Billing emails, affiliate links, and organization-level notification toggles.

How it works​

The companies document is read on each widget load and each dashboard request, so updates are picked up live. The timezone (an IANA string like Pacific/Auckland) is the source of truth for working-hours math; timezone_offset is a denormalized convenience that can drift. If the company is agency-managed, some of these defaults may be controlled by the agency.

Configuration & options​

Profile (CompanyModel)​

FieldDefaultWhat
company_name—Display name
website_url''Primary site (drives auto-scrape on signup)
industry''Used by AI prompts and the industry_match lead-score signal
agent_type'sales'Reserved / historical AI-agent classification
timezonePacific/AucklandIANA timezone — source of truth
timezone_offset720Convenience minutes-offset (denormalized)
languageenOrg-wide language (ISO code)

Branding​

  • Logo → companies.logo (a FileModel reference).
  • Email signature for transcript emails; invoice-email footer text (where the plan allows).
  • White-label widget branding is separate — see White-Label and the widget styling docs.

Working hours​

  • companies.working_hours[] + companies.timezone define when the widget is "online". Configured under Settings → Organization → Working Hours.

Billing emails​

  • companies.billing_emails[] — where invoice notifications and credit-low alerts go. May list multiple admins.

Visibility & mobile​

FieldDefaultWhat
visibilitytrueGlobal widget on/off
mobile_disablefalseHide the widget on mobile
widget_installedfalseAuto-set when the first event arrives
widget_installed_at—Timestamp of first event

Affiliate​

  • affiliate_link (URL) + affiliate_link_enabled (bool) — partner/referral programs (Rewardful).

Notifications​

  • companies.notifications holds org-level toggles: chat_transcript, call, missed_call, reports_email, daily_recap_email, slack_new_visitor, slack_hot_lead, etc. These are the ceiling — a per-user toggle only fires when the org-level one is on.

Privacy​

  • privacy_policy_text / privacy_policy_url — shown to visitors where applicable.

Agency-managed companies​

If the company is owned by an agency:

  • companies.agency_id is set.
  • companies.agency_self_account distinguishes the agency's own business account from agency-created client sub-accounts.
  • Some org settings (working hours, branding) may be controlled/inherited from the agency — admins should know the precedence. See Agency Overview.

Behaviors & edge cases​

  • "Why is the timezone wrong?" — the IANA timezone string is the source of truth; timezone_offset is convenience and can drift. Fix timezone.
  • "Team in two timezones — what do I set?" — use the primary office's; per-user timezone on each UserModel handles individual schedules. See Account Settings.
  • Changing industry does not retroactively re-score existing visitors — it applies to future signals only.
  • timezone changes affect working hours immediately on the next request.
  • widget_installed flips automatically when the first widget event arrives — admins can't toggle it manually.

Plan & limits​

  • Organization settings are available on all plans.
  • Some branding (e.g. invoice-email footer text, white-label widget footer) is plan-gated — see Plans & Subscriptions and White-Label. Verify per-tier specifics.

Technical implementation​

  • Model: CompanyModel — /home/bilal/Projects/knock-knock-app/backend/app/models/CompanyModel.js.
  • Controller / routes: CompanyController; e.g. PUT /company/:_id (profile), PUT /company/:_id/affiliate-link, PUT /company/:_id/lead-intelligence, PUT /company/:_id/webhooks. Admin-only: PUT /company/admin/free-period, PUT /company/admin/manual-ai-credits.
  • Frontend: frontend/src/views/settings/organization/Index.vue (+ Notifications.vue, WorkingHours.vue).
  • Working-hours/timezone drive widget state — see the widget module and backend service.