Skip to main content

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:

  1. installGhl() → POST /go-high-level/install-url/agency returns a GHL OAuth URL.
  2. 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).
  3. GHL redirects back to /ghlinstallation/install; the callback exchanges the code, then bounces to the agency dashboard with integration=go-high-level&success=true — or to /agency-setup when the install was started from the portal-setup checklist (return_path in state, allow-listed by AGENCY_INSTALL_RETURN_PATHS; see Dashboard → Portal setup).
  4. 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 (company sidebar_label → agency go_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 on appStore.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​

ActionRepository fnEndpointGate
Get agency install URLinstallGhl()POST /go-high-level/install-url/agencyagency.manage_settings (UI card)
Uninstall agencyuninstallGhl(agencyId)POST /go-high-level/uninstall/agencyconfirm dialog
Install for a companyinstallGhlForCompany(companyId)POST /go-high-level/install-url—
Uninstall from a companyuninstallGhlFromCompany(companyId)POST /go-high-level/uninstallagency owner (GhlClientModal)
Add / remove a client's menu linkaddGhlMenuLink / removeGhlMenuLink(companyId)POST / DELETE /go-high-level/menu-link?company_id=agency owner; agency-held links only

agency.go_high_level fields (AgencyModel)​

FieldNotes
access_token, refresh_token, access_token_expires_atOAuth tokens (access_token/refresh_token are select:false; the expiry is the connected marker)
user_type, user_id, company_idGHL identifiers
custom_menu_idGHL 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 in 324576a72 — 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 in Dashboard.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