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)
| Field | Default | What |
|---|---|---|
user_id | — | Agency owner |
name | '' | Agency name |
logo_file | null | Branding logo (FileModel ref) |
initial_ai_credits | 1500 | Pooled AI credits across sub-accounts unless customized |
total_sub_accounts / available_sub_accounts | 0 | Slot counts (granted vs. remaining) |
agency_packages[] / agency_addons[] | — | Refs to the agency's SKUs |
theme_colors | teal palette | primary, secondary, accent, sidebar_bg, sidebar_text, header_bg, header_text |
nox_name | null | White-label display name for the Nox assistant |
agent_k_name | null | White-label name for Agent K across every client |
nox_tag_prefix | null | Prefix for the GHL intent tags (<prefix>-intent-hot); null = nox |
reply_email | null | Sender for automated agency emails |
auto_invite_clients | true | Email the activation invite when a client is created (Add Client form overrides per client) |
opening_wallet_transfer_credits | 1000 | Super-admin-set minimum/default opening wallet transfer to a new client (credits, ≥100) |
wallet_credits / plan_wallet_credits | 0 | Agency wallet (1 credit = $0.01); the spendable total every gate reads |
wallet_low_notified_at | null | AgencyWalletLowJob 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_at | null | Set only by the "I'm an agency" signup paths — drives the own-site agency-plan paywall |
include_public_packages / include_public_addons | false / true | Catalog 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_enabled | false | Super-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_pilot | false | Temporary: only pilot agencies (and their sub-accounts) receive announcements; API only (PUT /agencies/admin/:agency_id/announcements-pilot) |
payment_issue | false | Flag for billing problems |
deleted_at | null | Soft-delete |
Agency packages (AgencyPackageModel, collection agency_packages)
The SKUs the agency sells to clients (custom title, description, features, limits, user count, AI credits, expiry):
| Field | Default | What |
|---|---|---|
name, description | — | Package identity |
amount | — | Custom price |
currency | usd | Any Stripe-supported currency |
sub_accounts | — | Sub-account slots granted by this plan |
trial | false | Trial package |
stripe_product_id / stripe_price_id | — | Stripe linkage |
package_type | private | private / public |
status | active | active / 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)
| Field | Default | What |
|---|---|---|
name, description, amount | — | Add-on identity + price |
currency | usd | |
type | sub_account | Add-on category |
billing_type | recurring | one_time / recurring |
visibility | public | private / public |
status | active | active / 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):
| Entry | Gate | What |
|---|---|---|
| Dashboard | agency.view_dashboard | Sub-account capacity + setup options |
| Clients → All Clients | agency.manage_clients | Client list + detail |
| Clients → Add Client / Add Client (GHL) | agency.add_client_subscription | Create forms (GHL only when connected) |
| Clients → Client Invitations | manage_clients + setting client_invitations_enabled | Prospecting email tool (Client Invitations) |
| Sell → Packages & Allocations | agency.manage_packages | Client packages |
| Sell → Playground / Shareable Playgrounds | agency.manage_playground | Demo sandboxes |
| Billing → Subscription / Phone Numbers | agency.subscription_payments | Plans, add-ons, Wallet, history, payment method; number rentals |
| Staff Members | owner only | Staff + permissions |
| Settings | none (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_idpoints to the agency.companies.agency_self_account: truemarks 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 withinsertOneto skip the Xero pre-save hook), a newAgencyModel(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.attachAgencymoves 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_creditsdefault 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; pluscompanies.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.