Connecting GoHighLevel

Overview

GoHighLevel (GHL) is the core CRM and marketing automation platform that powers af-gemini-connect. Connecting your GHL account enables:

• Client data synchronization
• Automated appointment scheduling
• Two-way SMS and calling
• Funnel and pipeline management
• White-label dashboard access

This guide walks you through connecting your agency's GHL account to af-gemini-connect.

Prerequisites

Before you begin, ensure you have:

• GoHighLevel account with agency admin privileges
• API credentials (Client ID and Client Secret) from GHL
• Admin access to af-gemini-connect

Step-by-Step Connection

1. Generate GHL API Credentials

1. Log into your GoHighLevel account as an agency admin
2. Navigate to Settings → API Settings
3. Click Create New API Key
4. Copy the Client ID and Client Secret (you'll need these shortly)

2. Access Agency GHL Configuration

1. In af-gemini-connect, go to Admin → Agency Settings
2. Select the GoHighLevel tab
3. Click Connect Account

3. Enter API Credentials

1. Paste your Client ID and Client Secret into the form
2. Click Authenticate
3. You'll be redirected to GHL's OAuth consent screen
4. Approve the connection

4. Configure Sync Settings

After authentication, configure:

• Sync Frequency: Real-time, hourly, or daily
• Client Sync: Enable to automatically import new clients
• Field Mapping: Map GHL custom fields to af-gemini-connect
• Webhook Endpoints: Set up callbacks for events (calls, SMS, appointments)

Field Bootstrap

af-gemini-connect supports 12 custom fields from GHL. During initial setup, you can choose which fields to enable:

1. Client Source — Where the lead came from
2. Lead Status — New, contacted, qualified, etc.
3. Priority — Low, medium, high, urgent
4. Service Type — The service they're interested in
5. Budget — Estimated project budget
6. Timeline — When they want to start
7. Notes — Internal notes
8. Tags — Custom tags for segmentation
9. Custom Field 1-4 — Four additional custom fields

Connection Health

Once connected, monitor your GHL integration in the Agency GHL dashboard:

• Connection Status: Active/Inactive
• Last Sync: Timestamp of last successful sync
• Sync Errors: Any errors encountered during sync
• Webhook Logs: Incoming/outgoing webhook events

Reconnecting After a Scope or App Update

Each client's GHL connection shows an App Version field on its Connections tab. When HighLevel is rejecting requests with a 401 "not authorized for this scope" error, or the App Version field says "Unknown — reconnect required," the client's connection was authorized before the app's current scopes were added. Adding a permission in the GHL Marketplace app does not upgrade connections that already granted access — each client has to reconnect once to pick up the new scopes.

To reconnect a client:

1. Open the client in Admin and go to the Connections tab.
2. Click Re-authorize on the GoHighLevel card.
3. Approve the OAuth screen in the popup that opens.
4. Confirm the App Version field now shows the current version number.

Disconnecting GHL

Click Disconnect on the GoHighLevel card to remove a client's connection. A confirmation prompt explains what this does:

• AF-Connect asks HighLevel to uninstall the app from that sub-account.
• Stored GHL credentials, the saved location ID, and any private-API-key fallback are cleared locally either way.
• Every website-level GHL form-sync binding for that client is turned off.

If HighLevel confirms the uninstall, you'll see a success message and can click Connect GHL to reinstall right away. If HighLevel doesn't confirm it (this can happen when the stored grant no longer allows a remote uninstall), you'll see a warning instead — local access is still removed, but you also need to manually remove AF-Connect from that sub-account's Settings → Installed Apps in GHL before reconnecting, or the reinstall can pick up the old grant.

Troubleshooting

"Invalid credentials" error

• Double-check your Client ID and Client Secret
• Ensure your GHL account has API access enabled
• Regenerate credentials if they've been compromised

Sync failures

• Check your sync frequency settings
• Verify webhook endpoints are reachable
• Review the connection health dashboard for specific errors

Missing client data

• Confirm client sync is enabled
• Check field mapping configuration
• Ensure clients are properly assigned to your agency

Next Steps

After connecting GHL, you can:

• Set up client-specific GHL connections
• Configure automated appointment scheduling
• Enable SMS campaigns
• Integrate with Google Calendar
• Connect Meta Ads for lead tracking

FAQ

Q: Can I connect multiple GHL accounts?
A: Yes, each client can have their own GHL connection in addition to the agency-level connection.

Q: What happens if I disconnect GHL?
A: See Disconnecting GHL above — it clears local credentials and website form-sync bindings, and tries to uninstall AF-Connect from the client's GHL sub-account.

Q: Are webhooks required?
A: Webhooks are optional but recommended for real-time updates (e.g., call recordings, SMS delivery status).