GHL CRM Mastery — GoHighLevel API v2 Skill

---

name: ghl-crm-mastery

description: Full read/write access to GoHighLevel CRM via API v2. Contacts, conversations, notes, opportunities, calendars, tags, tasks, forms, workflows, payments, and invoices. Includes rate-limit retries, safety guardrails, and real-time conversation support.

version: 1.3.0

author: SetupClaw.Tech

homepage: https://setupclaw.tech

metadata: { "openclaw": { "requires": { "env": ["GHL_API_KEY", "GHL_LOCATION_ID"], "bins": ["python3"] }, "primaryEnv": "GHL_API_KEY", "homepage": "https://setupclaw.tech" } }

---

# GHL CRM Mastery — GoHighLevel API v2 Skill

What This Does

Gives your agent full operational access to GoHighLevel — read, write, and real-time conversation management. Designed for CRM automation agents (appointment setting, lead qualification, pipeline management).

Contact Operations

Conversation Operations (Real-Time)

Notes

Pipeline & Opportunities

Calendars

Tags, Forms, Workflows

System

Real-Time Conversation Pattern

The agent uses this skill for instant lead response. The pattern:

**First touch (new lead, no prior research):**

1. `contacts search-phone` or `contacts search` — find the contact

2. `contacts get` — pull full record

3. `notes list` — check for existing research

4. If no research notes → run identity verification (separate skill/process)

5. `conversations get` — read conversation history

6. Craft personalized response

7. `conversations send` — reply via GHL

8. `notes add` — log research findings + what was sent

**Follow-up messages (contact already researched):**

1. `contacts get` — pull record (already has research in notes)

2. `conversations get` — read latest messages

3. Craft contextual reply (15-30 second target)

4. `conversations send` — reply

5. `notes add` — brief log of interaction

**Key principle:** Research happens ONCE per contact. After that, the agent reads its own notes and the conversation history, then replies fast. The goal is real-time chat feel — under 30 seconds for follow-ups.

Prerequisites

**Required environment variables** (must be set in your `.env` file):

GHL_API_KEY=your-private-integration-token
GHL_LOCATION_ID=your-location-id

**Required runtime:** `python3` (ships with macOS; verify with `python3 --version`).

Getting Your GHL Credentials

1. Log into GoHighLevel → Settings → Integrations → Private Integrations → Create New

2. Name it appropriately for your deployment

3. Enable all required scopes:

- contacts.readonly, contacts.write

- conversations.readonly, conversations.write

- conversations/message.readonly, conversations/message.write

- opportunities.readonly, opportunities.write

- calendars.readonly, calendars.write

- calendars/events.readonly, calendars/events.write

- locations/tags.readonly, locations/tags.write

- locations/tasks.readonly, locations/tasks.write

- forms.readonly, workflows.readonly

- payments/transactions.readonly, locations.readonly

- invoices.readonly, invoices.write, users.readonly

4. Copy the Private Integration Token → `GHL_API_KEY` in `.env`

5. Settings → Business Info → copy Location ID → `GHL_LOCATION_ID` in `.env`

Usage

All commands are run via the included Python CLI at `{baseDir}/scripts/ghl_api.py`:

export GHL_API_KEY=$(grep GHL_API_KEY ~/.openclaw/.env | cut -d= -f2)
export GHL_LOCATION_ID=$(grep GHL_LOCATION_ID ~/.openclaw/.env | cut -d= -f2)

# Test connection
python3 {baseDir}/scripts/ghl_api.py health

# Test contact lookup
python3 {baseDir}/scripts/ghl_api.py contacts list --limit 1

# Test conversation read
python3 {baseDir}/scripts/ghl_api.py conversations get --contact-id "YOUR_CONTACT_ID"

# Send a message
python3 {baseDir}/scripts/ghl_api.py conversations send --contact-id "CONTACT_ID" --message "Hello" --type sms

# Add a note
python3 {baseDir}/scripts/ghl_api.py notes add --contact-id "CONTACT_ID" --body "Research findings..."

Safety Guardrails (Non-Negotiable)

1. **Never create contacts** — GHL creates contacts automatically when forms are submitted, SMS received, or DMs received. Creating contacts manually risks duplicates. If a contact doesn't exist, flag to the appropriate channel.

2. **Never delete contacts** without explicit human confirmation in Slack

3. **Never send bulk SMS** without human approval

4. **Never modify workflows** — trigger only, never create/edit/delete

5. **Log every write operation** — every `conversations send` and `notes add` prints a timestamped log line

6. **TCPA compliance** — no SMS between 9PM and 8AM in the recipient's time zone (enforced by TCPA handler layer, not this skill)

Network Endpoints

This skill connects exclusively to the GoHighLevel API:

No other external endpoints are contacted. All credentials are read from local environment variables only.

Changelog

v1.3.0 (March 2026)

v1.2.0 (March 2026)

v1.0.0 (March 2026)