Skip to main content

Agency Dashboard

Audience: Agency-success / Sales / Support · Where in app: /agency (route name agency-dashboard) · Plan availability: Agency tier (verify specifics)

The dashboard is the landing screen of the agency portal. It answers two questions at a glance: how many client sub-accounts do I have left to install? and how do I add the next one? It is intentionally light on analytics — the heavy lifting (per-client metrics, revenue) lives in the companies, subscriptions, and admin revenue screens. Think of it as the agency owner's capacity gauge plus a launcher.

What it does​

  • Shows the agency's sub-account capacity: total slots, used, and available.
  • Offers three setup paths for adding a client: install on the agency's own website (self-account), connect a GoHighLevel agency account, or create a standard client account.
  • Surfaces a welcome / empty state for brand-new agencies that have bought no sub-accounts yet.
  • Provides quick links to the full companies list and the create-company flow.
  • Handles the GHL OAuth return — when GoHighLevel redirects back after an install, the dashboard reads the callback query params and routes the user on.

How it works​

The screen is driven entirely by the agency object in the app store (appStore.agency), which is loaded with the user session. There is no dedicated dashboard metrics endpoint — every number on this page is read from fields already on the agency record:

  • total_sub_accounts — slots granted by the agency's current package.
  • available_sub_accounts — slots not yet consumed by a client company.
  • Used is computed on the client as total − available.

If total_sub_accounts === 0, the page renders the empty "Welcome / buy sub accounts" state instead of the main content, with a single CTA to /agency/buy-sub-account (which redirects to the subscription plans tab — see Subscriptions).

The GHL connection state is read from agency.go_high_level.access_token (truthy = connected). The agency's own self-account state is read from appStore.company._id && appStore.company.agency_self_account.

Source: frontend/src/views/agency/Dashboard.vue.

Configuration & options​

Sub-account capacity card​

ElementSourceNotes
Used Accountstotal_sub_accounts − available_sub_accountsDark teal segment of the bar
Available Accountsagency.available_sub_accountsLight teal segment
Total Accountsagency.total_sub_accountsSum line
Progress barcomputed percentagesLabels hide below ~15–25% width

Setup options card​

OptionVisible whenActionPermission gate
Install on your own websitealwaysOpens "Setup own sub-account" modal (email field) → setupOwnCompany({ email }) → POST /agencies/setup-company; on success swaps the session to the new company and pushes to onboardingUnlink button only for agency owner (appStore.isAgencyOwner)
Connect with your GHL Agency AccountagencyHasPermission('agency.manage_settings')Opens GhlInstallModal → installGhl() → POST /go-high-level/install-url/agency, then redirects to the returned GHL OAuth URLHidden for staff lacking agency.manage_settings
Create Standard Client AccountalwaysRouter link to /agency/companies/create—

Each option shows a green check + an Unlink / Uninstall button once that path is already set up:

  • Unlink self account → unlinkSelfAccount(companyId) → PUT /company/unlink/:id (owner only).
  • Uninstall GHL → uninstallGhl(agency._id) → POST /go-high-level/uninstall/agency (confirm dialog first).

Stats strip​

Three cards: Total Sub-Accounts, Used Sub-Accounts, Available Sub-Accounts — all derived from the same three numbers above. No separate API call.

GHL callback handling (onMounted)​

Query params on returnBehavior
integration=go-high-level&success=true&company_name=...Redirect to agency-companies carrying the query (company-level install completed)
integration=go-high-level&success=true (no company)Toast "GoHighLevel connected", clear query params (agency-level install completed)

Portal setup (/agency-setup)​

views/agency/PortalSetup.vue (1d8ceb24, route agency-portal-setup, outside AgencyLayout, own top bar with Skip to dashboard / Logout) is where a freshly self-serve-created agency lands. It hosts components/agency/AgencyPortalChecklist.vue (redesigned in c85fee4b): a progress ring, headline "Let's build your portal" → "Your portal is taking shape" → "Your portal is live." (or "Your part is set up." for staff when the plan isn't active), "About N minutes left · do these in any order", and a numbered list — each row shows its minutes, Set up → (or Edit + a doneLine summary once done), the next undone step highlighted. The right column is the open step's panel, else AgencyPortalPreview.vue — a mock portal that fills in from real state (brand color/logo/name, domain, "GHL connected", finished sub-accounts, Live once the plan is active).

Steps live in composables/useAgencySetupSteps.js, shared by the checklist, the dashboard strip and the sidebar's Portal setup entry so all three count alike (visibleCards filters by permission and requiresPlan; loaded waits for both queries so a finished agency never flashes "steps left"):

Step (id)Done whenPanelGate
Agency name & branding (branding)logo_file && reply_emailAgencyBrandingSettings (GHL section hidden, Skip & do this later)manage_settings
White-label domain (white-label)any AgencyDomainModel rowWhiteLabelDomainsmanage_settings
Connect your GHL agency account (ghl)go_high_level.access_token_expires_atGHL install modal with return_path: '/agency-setup'manage_settings
Set up your first sub-account (sub-account)some sub-account has onboarding_completed"Whose site is this for?" — own site (runs /setup as the self-account) or create a client inline (name + email → createCompany)—
Choose a plan (plan, required → "Needed to go live")isAgencySubscriptionActive: status === 'active' (trial counts) and expiry in the future or unsetSubscriptionPlanssubscription_payments
Activate your wallet (wallet, requiresPlan)wallet_credits > 0SubscriptionAddonssubscription_payments

Plan step (05e656c5): ?step=plan (where an "I'm an agency" signup's clientSetup.finishAgencySignup and the own-site paywall's Choose my agency plan land) gives the plans full width with the checklist folded into a strip — "Last step to go live: choose your plan" / "Your other setup steps can wait." / Do other steps first — then "Choose your plan". onPlanSaved switches to a live screen: "Your agency portal is live", "Your free trial runs until <date>." (or "Your plan is active."), Go to my website (own site, via toOwnSite), Add your first client, Finish portal setup (N steps left). The top bar also gets Go to my website once the own site has onboarded.

All done → Continue to dashboard. The old pending-only checklist on the dashboard and its collapse/skippable modes are gone (66de668b). AgencyPlanInactiveBanner.vue sits above PortalSetup (hidden while the plan panel is open) whenever the plan isn't active: "Your agency subscription isn't active yet. Choose a plan to take your portal live." + Choose a plan for subscription_payments holders, else "Ask the agency owner to choose a plan." Running /setup for a sub-account from here stores a hand-off (common/helpers/agencyPortalHandoff.js, mode: impersonation | token); clientSetup.finish() restores the agency session and routes back to /agency-setup, and the last setup button reads Back to portal setup.

Dashboard setup strip (66de668b)​

components/agency/AgencySetupStrip.vue (on views/agency/Dashboard.vue) wraps the generic components/SetupStrip.vue (also used by the client portal's ClientSetupStrip): "Finish setting up your portal", a done/total ring, "N steps left · do them in any order", one chip per pending step (short: Branding, Domain, Connect GHL, First sub-account, Plan & billing, Wallet), Continue (first pending). openSetupCard routes chips via SETUP_CARD_ROUTES (branding → agency-settings-agency, white-label → agency-settings-white-label, sub-account → agency-companies-create, plan → agency-subscription-plans, wallet → agency-subscription-wallet; ghl opens the install modal). The ✕ menu (useAgencySetupStripDismissal, scope agency_setup) offers Remind me later (snoozes 3 then 7 days; the third hides it for good) or Don't show again, stored append-only in the user's viewed_screens (agency_setup_snooze:<ts>, agency_setup_strip_off) via PUT /user/viewed-screens, so it follows the user across devices. The sidebar's Portal setup entry stays regardless.

GHL return paths (91f571e92, 899534359): the install state can carry a return_path, allow-listed server-side because it round-trips through GHL — agency installs ['/agency-setup'] (AGENCY_INSTALL_RETURN_PATHS, default /agency), company installs ['/setup'] (COMPANY_INSTALL_RETURN_PATHS, used by the onboarding Agent K step; a failed install also returns there).

Playground (public demo sandbox)​

The agency portal grows two playground surfaces (routes /agency/playground, /agency/simple-playground → frontend/src/views/agency/{playground,simple-playground}/List.vue) for demoing the product to prospects with no login:

  • Anonymous playground — public /playground (views/playground/PlaygroundView.vue). POST /playground/init (rate-limited, fingerprinted, no auth) creates a temp user + company + subscription seeded with 100 AI credits and kicks off website scraping. Auto-expires: PlaygroundCompanyModel.expires_at = 24h.
  • Simple Playground (shareable) — setup wizard at /simple-playground (agency-authenticated via ?agency_create=1 / ?agency_edit=<id>), prospect link at /simple-playground/test?company_id=<id>. Never expires (expires_at holds a far-future sentinel). Share links are collaborative — anyone with the link can edit (GET|PUT /playground/shared-company). Renders white-labeled under the agency's branding/domain.

Mechanics (backend PlaygroundController + playgroundRoutes.js):

  • Every save path (owner, agency, shared link) goes through one whitelist — PLAYGROUND_SIMPLE_FIELDS / PLAYGROUND_NESTED_FIELDS (widget styling, ai_chat.* / ai_calling.* agent config, voice id/language, playground_redirect_url).
  • Widget wording defaults (47c36aae7): AgencyModel gained launcher_text, online_title_text, online_title_text_sub_heading, offline_title_text, offline_title_text_sub_heading, all default: null (null = leave the company default alone), seeded through the PlaygroundController whitelist. companyNameFromWebsite() derives the playground's name from the website URL, not the signup email domain (personal addresses were naming agents "assistant for gmail"); applyPlaygroundDefaults also applies inbound speech-behaviour and background-sound defaults.
  • Scrape progress: CompanyWebsiteModel.scrape_progress {processed, total, pages_checked, phase: queued|crawling|scraping|completed, updated_at} — declared in both backend and ms-communication (ms-comm WebhookController writes it from scraper webhooks). The public playground has no socket, so it polls /playground/scraping-status; the agency wizard uses usePlaygroundScrapeSocket.js. Deleting a website now calls ms-ai POST /cancel-scrapping so ScrapingBee credits stop burning.
  • Welcome video: POST /playground/agency/:id/video (streamed compression, replace/remove), with presets from the admin Default Videos library.
  • Review: GET /playground/agency/:id/calls — paginated voice-call recordings + chat conversations per playground.
  • Convert to real account: POST /playground/convert.
  • Agency management: GET /playground/agency/list|stats, CRUD on /playground/agency/:id, pause/resume, outbound toggle.
  • Wallet funding: New Playground needs a funded agency wallet (402 otherwise; UI shows Top up wallet to create). The create wizard's Starting credits ($ from your agency wallet) (default $1) is shown only to a logged-in agency and never in the website embed (?embed=1, where the server grants the $1 embed starter itself) — 3069a9bf. Deleting a playground refunds unspent credits to the agency wallet.
  • Share vs edit URLs (1a9c4054, faa4ef5d, 45a94c6b): the prospect share link is built on useShareOrigin (agency custom domain / white-label host — brand only, no session needed); the agency's edit link is built on getAppOrigin() + /playground?company_id=…&agency_id=…&edit because the editor needs the agency's login from this origin's storage (on the custom domain it had none → voices/AI Engine 401).
  • Email the demo link (d10c15c4): Shareable Playgrounds row → EmailPlaygroundLinkModal → POST /playground/agency/:id/share-email — branded agency email, ≤10 addresses, optional note; gated like other playground actions.
  • Assistant name: the playground company payload now resolves assistant_name = company.knox.agent_name || agency.nox_name || '' (same precedence as the voice), closing a white-label leak where renamed agencies showed "NOX" (5d3db85a7).
  • Staff access to both playground lists is agency.manage_playground.
  • Super-admin: /admin/playground (views/admin/playground/List.vue) — list + stats with a Credits column (remaining plan + purchased credits per playground; GET /playground/admin/list|stats).

Behaviors & edge cases​

  • Zero capacity = empty state. An agency that has subscribed but somehow has total_sub_accounts = 0 sees only the buy-sub-accounts CTA; the setup cards and stats are hidden.
  • Self-account setup re-authenticates. setupOwnCompany returns a fresh token, user, company, and subscription; the store is replaced in place and the user is pushed to onboarding. If the onboarding route is missing it stays on the dashboard and invalidates the agency query.
  • Staff visibility. Staff without agency.manage_settings never see the "Connect GHL" card or the GHL setup step. The "Unlink" self-account control is owner-only regardless of permissions.
  • Numbers can lag. Because the cards read the cached agency object, creating/removing a company elsewhere only updates here after loadUserInfo() / query invalidation. A hard refresh is the reliable resync.

Plan & limits​

  • The dashboard is part of the agency portal, which is its own subscription tier (verify exact plan name/pricing).
  • total_sub_accounts is granted by the agency's package; see Subscriptions and Packages. The dashboard itself imposes no limits — it only reports them.

Technical implementation​

  • View: frontend/src/views/agency/Dashboard.vue
  • Route: frontend/src/router/agency.js → name agency-dashboard, path /agency, layout AgencyLayout.vue, allowedUserType: [AGENCY, AGENCY_STAFF]
  • Store: frontend/src/store/app.js (agency, company, isAgencyOwner, agencyHasPermission)
  • Repositories: frontend/src/repositories/agency/index.js (setupOwnCompany, unlinkSelfAccount, uninstallGhl, installGhl)
  • Backend: AgencyController (setupCompany, unInstallGhl), GoHighLevelService for install URLs — see backend service and CRM integration subsystem
  • Model: AgencyModel (backend/app/models/AgencyModel.js)