GHL Integration
Audience: Agency-success / Support / Engineering · Where in app: Settings → Agency (GoHighLevel Integration), /agency/ghl-instructions, dashboard "Connect GHL" card, /agency/companies/create-ghl, All Clients → LeadConnector column · Plan availability: Agency tier; connect gated by agency.manage_settings, create gated by agency.add_client_subscription
This page covers the agency-scope GoHighLevel integration: connecting the agency's GHL agency account, creating Knock Knock client accounts mapped to GHL sub-accounts, managing each client's connection (app page, menu link, disconnect) from the portal, and how connections from the retired v1 app are handled. For the cross-app mechanics (token refresh, webhooks, identity), see the CRM integration subsystem and the GoHighLevel integration module.
What it does
- Connect an agency's GoHighLevel agency account to Knock Knock via OAuth.
- Create client accounts from GHL — provision a Knock Knock account per GHL sub-account and get an install URL to map them.
- Disconnect / uninstall the GHL app at agency scope.
- Manage each client's connection from the client list (
GhlClientModal): status, app page, menu link, disconnect. - Flags agency and client connections still on the retired v1 app.
How it works
Connecting the agency
From the dashboard "Connect with your GHL Agency Account" card (visible with agency.manage_settings) or the GHL Instructions screen:
installGhl()→POST /go-high-level/install-url/agencyreturns a GHL OAuth URL.- The user is redirected to GoHighLevel and must link the agency main account (not a sub-account), choosing "Install under all locations" and "Enable automatic installations" (both pre-checked in
GhlInstallModal). - GHL redirects back to
/ghlinstallation/install; the callback exchanges the code, then bounces to the agency dashboard withintegration=go-high-level&success=true— or to/agency-setupwhen the install was started from the portal-setup checklist (return_pathinstate, allow-listed byAGENCY_INSTALL_RETURN_PATHS; see Dashboard → Portal setup). - Tokens land in
agency.go_high_level(access_token,refresh_token,access_token_expires_at,user_type,company_id,custom_menu_id,app_version: 'v2').
Connected state is read from agency.go_high_level.access_token_expires_at — the tokens are select:false and never reach the browser (15fda18a9, frontend 42cdc6d1 switched the dashboard, settings, portal checklist, client-create and admin agency detail checks).
Creating a client from GHL
With GHL connected, /agency/companies/create-ghl (createCompanyForGHL, POST /agencies/companies/ghl) provisions a Knock Knock company + web_owner user + default chatbot + a client subscription on the chosen package, decrements available_sub_accounts, and returns a ghl_install_url. The agency follows that URL to install Knock Knock into the matching GHL sub-account. One Knock Knock account per GHL client. See Managing Companies for the full form/fields.
Managing a client's connection (e2d50299)
views/agency/companies/List.vue has a LeadConnector column (only when the agency itself is connected), replacing the old "Map Go High Level" cell and "Uninstall Go High Level" row action:
- Unmapped → Connect →
ConfirmDialog"Connect LeadConnector?" →installGhlForCompany(POST /go-high-level/install-url). - Mapped → Connected (or red Old app: stopped when
usesRetiredApp) + summary (App page/Reconnect needed,+ menu link) · Manage →components/agency/GhlClientModal.vue(accessible dialog, Escape closes): Status, Sub-account ID, App version (Current / Old (retired)), Sidebar name (companysidebar_label→ agencygo_high_level_name→ agency name); app page state (Shown / Hidden / Not available); menu link state +menuLinkAdvice; Add link / Remove link (POST/DELETE /go-high-level/menu-link?company_id=) for agency-held links only — a client-held link (custom_menu_held_by: 'company') shows "only they can change it"; Disconnect (uninstallGhlFromCompany). Link and disconnect actions are gated onappStore.isAgencyOwner(canManage).
Menu-link ownership and the backend rules are in GoHighLevel → Menu links. The company-side Menu link tab leaves agency-held links to the agency.
Agency settings (views/agency/settings/Agency.vue)
The GoHighLevel Integration section shows connection status first (plus a red "Connected through the old app…" line when agencyUsesRetiredApp), then GoHighLevel Name (hint: it's also the Custom Page sidebar name unless a client sets its own) and Contact Tag Prefix, then "How your clients open the app in LeadConnector" — App page (recommended) / Menu link (old option) cards (3b85366f, reworded ddde8d0e) and a <details> "Want your name in the menu right away? Show me how" wrapping GhlSidebarScriptHelp (the Custom JS steps: agency view → Settings → Company → White Label → Custom JS → Save changes). See Custom Page sidebar name.
Retired v1 app
Since 135988040 there is one marketplace app. Every install stamps app_version: 'v2'; the agency-level go_high_level_install_version override, _appCreds and installAppVersionForAgency are gone (and the admin per-agency selector with them, frontend b217d0bd). An agency token whose app_version isn't 'v2' (the schema default 'v1' covers old rows) is refused in getAgencyClient with GHL_APP_RETIRED; AgencyLayout mounts GhlAppUpdateBanner scope="agency" — a red, non-dismissible "LeadConnector has stopped syncing: your agency's account is connected through the old app…" bar whose Reconnect goes to /agency/settings/agency. Fix = Disconnect, then Connect GHL again.
Configuration & options
Connect / disconnect actions
| Action | Repository fn | Endpoint | Gate |
|---|---|---|---|
| Get agency install URL | installGhl() | POST /go-high-level/install-url/agency | agency.manage_settings (UI card) |
| Uninstall agency | uninstallGhl(agencyId) | POST /go-high-level/uninstall/agency | confirm dialog |
| Install for a company | installGhlForCompany(companyId) | POST /go-high-level/install-url | — |
| Uninstall from a company | uninstallGhlFromCompany(companyId) | POST /go-high-level/uninstall | agency owner (GhlClientModal) |
| Add / remove a client's menu link | addGhlMenuLink / removeGhlMenuLink(companyId) | POST / DELETE /go-high-level/menu-link?company_id= | agency owner; agency-held links only |
agency.go_high_level fields (AgencyModel)
| Field | Notes |
|---|---|
access_token, refresh_token, access_token_expires_at | OAuth tokens (access_token/refresh_token are select:false; the expiry is the connected marker) |
user_type, user_id, company_id | GHL identifiers |
custom_menu_id | GHL custom menu link |
app_version | 'v2' = current app; anything else (incl. the v1 default) is the retired app and is refused |
Install modal copy (GhlInstallModal.vue)
Instructs: link the GHL Agency main account (not a sub-account); both "Install under all locations" and "Enable automatic installations" are enforced (checked + disabled).
Intent tag prefix
agency.nox_tag_prefix (Settings → Agency → GoHighLevel Integration → Contact Tag Prefix, 776de5881) renames the intent tags Nox writes on client contacts: <prefix>-identified, <prefix>-intent-warm, <prefix>-intent-hot. null = nox, so existing workflows keep firing. Validated on save (lower-cased; ≤30 chars of letters/digits/space/-/_, alphanumeric at both ends). Read by NoxGhlActionService._agencyNox alongside nox_name. Existing tags are not renamed.
What syncs at agency scope
- Connection / tokens at the agency level enable creating and mapping GHL client sub-accounts.
- Per-client data sync (contacts, conversations, opportunities, webhooks) happens at company scope once Knock Knock is installed into a sub-account — that machinery is documented in the CRM integration subsystem and GoHighLevel module, not here.
- The public
GET /agencies/load-data-on-ghl/load(loadAgencyAdminDataOnGHL) was deleted in324576a72— it streamed every agency email and had no callers.
Behaviors & edge cases
- Agency account, not sub-account. The modal and instructions are explicit: connect the GHL agency main account. Linking a sub-account here is a misconfiguration.
- Retired = dead, not degraded. A v1 token is refused before refresh (
GHL_APP_RETIRED), so agency and client features stop until reinstall — there is no fallback path. - Menu links belong to whoever's GHL agency holds them. The agency can't remove a link a client created in its own GHL agency, and vice versa (403 naming the other side).
- Capacity still applies. Creating a GHL client consumes a sub-account slot and is blocked at
available_sub_accounts < 1. - Disconnect is a confirm action. Uninstalling GHL disables GHL features for the agency; best-effort uninstall on the GHL side, local state cleared regardless.
Plan & limits
- GHL connection is an agency-tier capability; client creation is bounded by sub-account capacity (see Subscriptions). Verify any GHL-specific plan gating.
Technical implementation
- Views / components:
frontend/src/views/agency/GhlInstructions.vue,frontend/src/components/agency/GhlInstallModal.vue,frontend/src/views/agency/companies/CreateGHL.vue, dashboard card inDashboard.vue - Repository:
frontend/src/repositories/agency/index.js(installGhl,uninstallGhl,installGhlForCompany,uninstallGhlFromCompany) - Service:
backend/app/services/GoHighLevelService.js(getInstallUrl,getAccessToken,_assertCurrentApp) - Controllers:
backend/app/controllers/AgencyController.js(createCompanyForGHL,unInstallGhl);GoHighLevelController.menuLink - Model:
AgencyModel(go_high_level,go_high_level_name) - Client management:
frontend/src/components/agency/GhlClientModal.vue,views/agency/companies/List.vue,common/helpers/ghlMenuLink.js,components/GhlAppUpdateBanner.vue - See also: CRM integration subsystem, GoHighLevel integration module, backend service
Related
- Agency Portal — Overview
- Managing Companies — create-from-GHL flow
- Dashboard — the Connect-GHL card
- Subscriptions — sub-account capacity