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
| Element | Source | Notes |
|---|---|---|
| Used Accounts | total_sub_accounts − available_sub_accounts | Dark teal segment of the bar |
| Available Accounts | agency.available_sub_accounts | Light teal segment |
| Total Accounts | agency.total_sub_accounts | Sum line |
| Progress bar | computed percentages | Labels hide below ~15–25% width |
Setup options card
| Option | Visible when | Action | Permission gate |
|---|---|---|---|
| Install on your own website | always | Opens "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 onboarding | Unlink button only for agency owner (appStore.isAgencyOwner) |
| Connect with your GHL Agency Account | agencyHasPermission('agency.manage_settings') | Opens GhlInstallModal → installGhl() → POST /go-high-level/install-url/agency, then redirects to the returned GHL OAuth URL | Hidden for staff lacking agency.manage_settings |
| Create Standard Client Account | always | Router 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 return | Behavior |
|---|---|
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 when | Panel | Gate |
|---|---|---|---|
Agency name & branding (branding) | logo_file && reply_email | AgencyBrandingSettings (GHL section hidden, Skip & do this later) | manage_settings |
White-label domain (white-label) | any AgencyDomainModel row | WhiteLabelDomains | manage_settings |
Connect your GHL agency account (ghl) | go_high_level.access_token_expires_at | GHL 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 unset | SubscriptionPlans | subscription_payments |
Activate your wallet (wallet, requiresPlan) | wallet_credits > 0 | SubscriptionAddons | subscription_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_atholds 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):AgencyModelgainedlauncher_text,online_title_text,online_title_text_sub_heading,offline_title_text,offline_title_text_sub_heading, alldefault: null(null = leave the company default alone), seeded through thePlaygroundControllerwhitelist.companyNameFromWebsite()derives the playground's name from the website URL, not the signup email domain (personal addresses were naming agents "assistant for gmail");applyPlaygroundDefaultsalso 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-commWebhookControllerwrites it from scraper webhooks). The public playground has no socket, so it polls/playground/scraping-status; the agency wizard usesusePlaygroundScrapeSocket.js. Deleting a website now calls ms-aiPOST /cancel-scrappingso 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 onuseShareOrigin(agency custom domain / white-label host — brand only, no session needed); the agency's edit link is built ongetAppOrigin()+/playground?company_id=…&agency_id=…&editbecause 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 = 0sees only the buy-sub-accounts CTA; the setup cards and stats are hidden. - Self-account setup re-authenticates.
setupOwnCompanyreturns a freshtoken,user,company, andsubscription; 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 theagencyquery. - Staff visibility. Staff without
agency.manage_settingsnever 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_accountsis 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→ nameagency-dashboard, path/agency, layoutAgencyLayout.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),GoHighLevelServicefor install URLs — see backend service and CRM integration subsystem - Model:
AgencyModel(backend/app/models/AgencyModel.js)