Skip to main content

Agency Portal — Overview

Audience: Sales / Agency-success / Management (engineers for the technical section) · Where in app: Agency Portal (separate nav once an agency exists) · Plan availability: Enterprise / agency tier (the agency portal is its own subscription)

The agency portal turns Knock Knock into a reseller-friendly platform. An agency manages many client companies ("sub-accounts") under its own brand, sets its own pricing via custom packages, and bills its clients while paying Knock Knock for the underlying platform.

What it does​

  • One owner manages all sub-accounts from a single dashboard.
  • Sell at any markup with agency packages and agency add-ons (custom pricing/currency).
  • Create client accounts directly (no client self-signup needed) — including from a GoHighLevel sub-account — and invite, fund, restrict ("Agency Controls") and pause them.
  • Self-serve agency signup from onboarding, or self-conversion of a direct account (no invite, no admin review), with a portal-setup checklist. AppSumo agency tiers come in through the same path (AppSumo Licensing).
  • White-label the widget, portal (custom domain), emails, the Nox assistant name, and the desktop app.
  • Track per-sub-account revenue and churn; manage agency staff with scoped permissions.

How it works​

An AgencyModel row (collection agencies) is owned by a user and holds the agency's brand, sub-account counts, and references to its packages/add-ons. The agency subscribes to an agency package (AgencyPackageModel) which grants a number of sub-account slots; Stripe bills the agency. The agency then creates client companies, each linked back via companies.agency_id. Each sub-account can have its own company subscription, but the company admin can't change its own plan — they see a "Contact agency" gate. When the agency's subscription renews, sub-account allowances and AI credits are refreshed across all its companies.

Configuration & options​

Agency model (AgencyModel, collection agencies)​

FieldDefaultWhat
user_id—Agency owner
name''Agency name
logo_filenullBranding logo (FileModel ref)
initial_ai_credits1500Pooled AI credits across sub-accounts unless customized
total_sub_accounts / available_sub_accounts0Slot counts (granted vs. remaining)
agency_packages[] / agency_addons[]—Refs to the agency's SKUs
theme_colorsteal paletteprimary, secondary, accent, sidebar_bg, sidebar_text, header_bg, header_text
nox_namenullWhite-label display name for the Nox assistant
agent_k_namenullWhite-label name for Agent K across every client
nox_tag_prefixnullPrefix for the GHL intent tags (<prefix>-intent-hot); null = nox
reply_emailnullSender for automated agency emails
auto_invite_clientstrueEmail the activation invite when a client is created (Add Client form overrides per client)
opening_wallet_transfer_credits1000Super-admin-set minimum/default opening wallet transfer to a new client (credits, ≥100)
wallet_credits / plan_wallet_credits0Agency wallet (1 credit = $0.01); the spendable total every gate reads
wallet_low_notified_atnullAgencyWalletLowJob once-per-dip marker
partner_listing—Implementation Partners directory listing (shared partnerListingSchema)
go_high_level—GHL OAuth tokens + config (app_version must be v2; the v1 default = retired app)
trial / trial_duration / trial_activated_at / expiry—Agency trial state (self-serve signups: trial: true, trial_duration: 7)
self_serve_signup_atnullSet only by the "I'm an agency" signup paths — drives the own-site agency-plan paywall
include_public_packages / include_public_addonsfalse / trueCatalog visibility with agency_packages / agency_addons — see Subscriptions
default_knowledge_base—{documents[{file}], texts[{title,content}]} copied into new sub-accounts — see Managing Companies
bot_flow_enabledfalseSuper-admin switch fanned out to every client sub-account
platform_api.client_defaults—Platform API new-client defaults — see Platform API
appsumo_extra_seats / appsumo_no_agency / appsumo_seat_checkouts—AppSumo seat purchases and closed-agency state
announcements_pilotfalseTemporary: only pilot agencies (and their sub-accounts) receive announcements; API only (PUT /agencies/admin/:agency_id/announcements-pilot)
payment_issuefalseFlag for billing problems
deleted_atnullSoft-delete

Agency packages (AgencyPackageModel, collection agency_packages)​

The SKUs the agency sells to clients (custom title, description, features, limits, user count, AI credits, expiry):

FieldDefaultWhat
name, description—Package identity
amount—Custom price
currencyusdAny Stripe-supported currency
sub_accounts—Sub-account slots granted by this plan
trialfalseTrial package
stripe_product_id / stripe_price_id—Stripe linkage
package_typeprivateprivate / public
statusactiveactive / inactive

Packages can also restrict access by email allow-list, set an expiry (for time-limited promos), and define user counts and AI-credit allotments (per the customer-facing Packages screen).

Agency add-ons (AgencyAddonModel, collection agency_addons)​

FieldDefaultWhat
name, description, amount—Add-on identity + price
currencyusd
typesub_accountAdd-on category
billing_typerecurringone_time / recurring
visibilitypublicprivate / public
statusactiveactive / inactive

The most common add-on is extra sub-accounts. Add-ons can be bought for the agency itself or applied to a specific client company.

Agency subscription (AgencySubscriptionModel, collection agency_subscription)​

agency_id, user_id, package_id, new_package_id (scheduled downgrade at cycle end), expiry_date, is_trial, stripe_id, status (active / inactive / canceled), canceled_at, cancel_reason. Renews monthly.

Agency staff​

Staff are UserModel rows with user_type: 'agency_staff', linked via agency_id and a parent (the agency owner), carrying a permissions[] array. Ten permissions (agency.view_dashboard, manage_clients, manage_playground, add_client_subscription, edit_clients, disable_clients, impersonate_clients, subscription_payments, manage_packages, manage_settings) — full table in Staff Management. Staff can be imported from a client company. Routes: /agency/staff* (owner-only).

Agency portal screens​

Sidebar (components/agency/AgencyNavigationSidebar.vue, rebuilt on the company portal's NavItem in 2de4c596; groups Clients / Sell / Billing plus unlabelled home and manage groups, each entry permission-gated, empty groups dropped):

EntryGateWhat
Dashboardagency.view_dashboardSub-account capacity + setup options
Clients → All Clientsagency.manage_clientsClient list + detail
Clients → Add Client / Add Client (GHL)agency.add_client_subscriptionCreate forms (GHL only when connected)
Clients → Client Invitationsmanage_clients + setting client_invitations_enabledProspecting email tool (Client Invitations)
Sell → Packages & Allocationsagency.manage_packagesClient packages
Sell → Playground / Shareable Playgroundsagency.manage_playgroundDemo sandboxes
Billing → Subscription / Phone Numbersagency.subscription_paymentsPlans, add-ons, Wallet, history, payment method; number rentals
Staff Membersowner onlyStaff + permissions
Settingsnone (hosts Profile)Agency · AI Assistant · Client Updates · Client Support · GoHighLevel · Partner Listing · White Label · Platform APIs (platform_api.enabled) · Knowledge Base · Recording Privacy · Signup Page · Payments (owner only, Client Billing) · Profile (views/agency/settings/Layout.vue)

Top: MyWebsiteSwitch.vue (My website) once the agency has an own site — one click to its dashboard; the company sidebar has the mirror Agency Portal switch. Switching back and forth pops the impersonation stack instead of growing it (2fa31852). AgencySeatLimitLock and AgencyClientWalletLowBanner mount in AgencyLayout.

Footer: a Portal setup n/m link while setup steps remain (useAgencySetupSteps, the same counting as the checklist and dashboard strip), a Wallet pill (amber when low, agency.subscription_payments), and the profile row whose menu holds Switch (to the selected company), Appearance (Light/Dark/System), Logout (hidden in a GHL session) and the version; the popover also carries the AppSumoPlanBadge and, after the low-wallet bar is dismissed, AgencyWalletLowNotice. Collapse follows the company portal: saved preference, forced collapsed under 900px, narrower under 1100px.

Outside the layout: /agency-setup (views/agency/PortalSetup.vue) — the post-signup setup checklist, see Dashboard.

Sub-accounts (companies under an agency)​

  • companies.agency_id points to the agency.
  • companies.agency_self_account: true marks the agency's own business company vs. a client sub-account.
  • Subscription bills the agency, not the company directly; the company admin sees a "Contact agency" gate on plan changes.
  • Create a sub-account via Add Company (POST /agencies/companies) or Add from GHL (POST /agencies/companies/ghl).
  • Login as Owner (impersonation) lets agency staff configure or support a client; a "Back to Agency" control returns them.
  • companies.paused_at / paused_by — agency pause (widget, inbound AI, SMS/WhatsApp AI and the client's operational API all stop; subscription untouched). companies.agency_client_permissions — the Agency Controls allow-list. Both in Managing Companies.

Self-serve agency signup​

POST /agencies/self-serve (AgencyController.createSelfServeAgency) runs when a self-serve web owner answers I'm an agency on the /setup "Let's set you up" step (AccountTypeStep). Since 05e656c5 the frontend first creates the company — POST /user/company { for_agency: true } (no welcome wallet) — then converts it, so the business becomes the agency's own site and onboarding carries on with it as the demo:

  • A second user with the same email and user_type: 'agency' (inserted with insertOne to skip the Xero pre-save hook), a new AgencyModel (total_sub_accounts / available_sub_accounts = 1, selfServeAgencyFields() → self_serve_signup_at, trial: true, trial_duration: 7), and the $20 agency grant (not AppSumo).
  • AppSumoService.attachAgency moves an AppSumo tier over (see AppSumo Licensing).
  • The company is re-parented (agency_id, agency_self_account: true), its subscription adopted if it had one, else put on the agency's private package via _ensureSubAccountSubscription; a welcome wallet carries over less the extra $5, then the $5 own-site grant (moved from the agency wallet for AppSumo).
  • Any pending admin-reviewed conversion request is closed as approved. Idempotent; returns a token for the agency user (both users share an email).
  • Refused: non-owners (403), companies already under an agency (400), certification partner companies (400), and — 3e60b820e — signing into an existing agency with the same email unless the caller is verified (OTP/Google/Apple; 403 "Please verify your email before setting up an agency").

clientSetup.finish() then signs in as the agency and opens agency-portal-setup?step=plan ("Your demo site is ready. Now choose your agency plan."). Until a plan is active the own site is paywalled in agency mode — see Free Session, Paywall & Trials. _createSelfServeAgencyWithoutCompany (company-less signup user flipped to user_type: 'agency') remains for callers that reach it with no company.

Direct → agency conversion​

Self-conversion (a8d197a59, frontend useAgencySelfConvert.js + components/agency/AgencyConvertDialog.vue): Settings menu Convert to Agency Account and the hard paywall link. Shown to a web_owner who isn't an agency, has no agency_id and no company.appsumo_plan.

  • GET /agencies/self-convert/options?company_id=[&agency_package_id=] — eligible plans (public, non-trial, Stripe-priced agency packages) and a price preview.
  • POST /agencies/self-convert {company_id, agency_package_id?} — no admin review. Without a paid plan: Convert now. With a Stripe plan: pick an agency plan, Switch plan & convert.

Admin-approved path (56120f24d): POST /agencies/setup-agency-account (request; emails hello@knockknockapp.ai), GET /agencies/conversion-request (own status), admin GET /agencies/conversion-requests, GET …/:id/preview?agency_package_id=, POST …/:id/approve {agency_package_id}, POST …/:id/reject. Admin → Agency Conversion Requests ("Approve Agency Conversion" dialog; the admin may pick private plans; a plan is required only with a Stripe subscription — AGENCY_PLAN_REQUIRED). The card-less customer request UI (1e8925c1) was removed the next day (e7757552), so the queue only receives old or API-made requests. Approval sends a bell notification "Your agency account is approved" (relation agency_conversion_approved; App.vue reloads user info on it) and the "Your Agency Account Has Been Approved!" email. A self-convert auto-approves pending requests.

Shared core (_convertCompanyToAgency): blocked for existing agencies, certification partners, AppSumo tiers without allow_agency, or an email already on an agency user. Creates the agency user + agency (total_sub_accounts: 1, available_sub_accounts: 0 — the own site takes the seat) + $20 grant, sets agency_id + agency_self_account: true. It does not set self_serve_signup_at or trial fields. Stripe (StripeService.switchSubscriptionPrice, a09da6dd4): the same subscription moves to the agency price, prorated and charged now (nothing on trial); add-on items removed and recurring_addons revoked; cancel_at_period_end lifted. A declined card returns 402 and is fully undone. _adoptSwitchedSubscription creates the agency subscription, applies seats and plan wallet, and nulls the direct row's stripe_id. Without a Stripe plan the account goes on the agency's private $0 package and the welcome wallet carries over.

Admin "Add existing company" (9a95dedde, frontend 3045d15c): POST /agencies/admin/:agency_id/companies {company_id, package_id?} moves a direct company under an agency — one seat, its own Stripe billing cancelled at period end, an agency package, wallet kept; rolls back (502) if every Stripe cancel fails. The modal never sends package_id. Moved companies inherit agency flags (Bot Flow) but not the default knowledge base.

Behaviors & edge cases​

  • Upgrade vs. downgrade: agency upgrades apply immediately (prorated); downgrades are deferred to cycle end via new_package_id. Same model as direct billing — see Plans & Subscriptions.
  • Revoking agency access does not auto-convert sub-accounts to direct billing — that's a manual conversion.
  • Inherited defaults: sub-accounts inherit some agency defaults (working hours, branding) — admins should understand precedence.
  • GHL is agency-aware: company creation, tagging on cancel/reactivate, per-client connection management and menu links flow through the agency — see GHL Integration. Connections from the retired v1 app are refused (GHL_APP_RETIRED).
  • Payment-issue flag: agencies.payment_issue / per-company flags (/agencies/payment-issue, /agencies/dismiss-payment-issue) surface billing problems.
  • Agency deletion: soft-delete (deleted_at) plus a hard-delete endpoint exist; the customer-facing "Danger Zone" full self-serve deletion is marked coming soon.

Plan & limits​

  • The agency portal is the agency/Enterprise tier — itself a paid subscription.
  • initial_ai_credits default is 1500 (pooled). Per-package sub-account slots, pricing, and AI credits are agency-defined — verify specific numbers against the live data; do not quote fixed prices.

Technical implementation​

  • Models: AgencyModel, AgencyPackageModel, AgencyAddonModel, AgencySubscriptionModel, AgencyDomainModel; plus companies.agency_id / agency_self_account / widget_whitelabel — /home/bilal/Projects/knock-knock-app/backend/app/models/.
  • Controllers/routes: AgencyController (/agencies* — subscribe, change-package, buy-addon, create/update/pause company, client-permissions, setup-session, send-invite, self-serve, payment-issue, conversion-requests), AgencyStaffController (/agency/staff*), AgencyDomainController (/agency-domains*).
  • Frontend: frontend/src/views/agency/ (Dashboard, PortalSetup, companies/, SubscriptionManagement, WhiteLabelDomains, settings/, playground/, simple-playground/) + components/agency/{AgencyPermissionGate,AgencyPortalChecklist,ClientAccessPicker}.vue.
  • Billing flows through Stripe + Xero — see Payments & Invoices. White-label detail: White-Label. CRM/GHL: /subsystems/crm-integration. Engineering: backend service.