convez.ai
SkillIntegração & APIsIntermediário
LUIZOTAVIOENGENHARIADIGITAL

Skill /ghl para Claude Code — Integração GoHighLevel

LUIZOTAVIOENGENHARIADIGITAL/ghl-claude-skill

Controle seu CRM GoHighLevel direto do Claude — sem deixar o terminal

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill Python que integra o Claude Code ao GoHighLevel, permitindo criar e atualizar contatos, oportunidades, campos personalizados e tags via API v2. Resolve pegadinhas comuns (Cloudflare, deduplicação, normalização de telefone) e importa bases inteiras de planilhas com segurança.

Instalação

$npx convez-ai LUIZOTAVIOENGENHARIADIGITAL/ghl-claude-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Importar bases de leads com deduplicação automática
  • Criar e atualizar contatos e oportunidades em massa
  • Gerenciar campos personalizados e tags por automação
  • Integrar pipelines de dados com o GHL

Veredito

Skill bem-documentada e pragmática que resolve frustações reais da API v2 do GHL (Cloudflare, dedup fraca, normalizações). Ideal para quem usa GoHighLevel e quer automatizar operações repetitivas via IA — requer credenciais e conhecimento da plataforma.

README

A tradução para o português deste README ainda está na fila.

🚀 Skill /ghl para Claude Code — opere o GoHighLevel direto do terminal

Uma skill do Claude Code que transforma a IA num operador do seu CRM GoHighLevel (GHL / HighLevel). Com um simples /ghl você passa a criar e atualizar contatos, oportunidades, campos personalizados e tags, além de importar bases inteiras (planilhas) com deduplicação — tudo via API v2, sem abrir a interface pra tarefa repetitiva.

Construída e disponibilizada pelo Luiz Otávio — Engenheiro Digital, pra comunidade. Pega, instala, e bota a IA pra trabalhar no seu GHL. 100% genérica e sem nenhum segredo: você pluga as SUAS credenciais.


🤔 O que é o GoHighLevel (GHL)?

GoHighLevel é uma plataforma all-in-one de CRM e automação de marketing muito usada por agências e infoprodutores: funis (pipelines), contatos, oportunidades, campos personalizados, tags, automações (workflows), smart lists, disparos etc. Ele expõe uma API v2 em services.leadconnectorhq.com.

🧠 O que essa skill faz por você

Depois de instalada, é só conversar com o Claude. Exemplos do que ele resolve:

  • "Cria um contato pra fulano com email X e telefone Y, e abre uma oportunidade no funil de vendas."
  • "Importa essa planilha de 2 mil leads, sem duplicar quem já existe."
  • "Lista meus funis, etapas e campos personalizados com os IDs."
  • "Cria um campo personalizado Lead Score numérico."
  • "Adiciona a tag status:cliente-ativo em todo mundo que fechou."
  • "Acha o contato com esse telefone e me mostra."

E, importante: a skill já conhece as pegadinhas do GHL (veja abaixo), então o Claude não cai nos erros que fazem todo mundo perder horas.

⚠️ As pegadinhas que essa skill já resolve

  1. Cloudflare "Error 1010". Sem um User-Agent de navegador, o GHL bloqueia chamadas de bibliotecas Python padrão. O cliente já injeta o header certo.
  2. A API v2 não cria tudo. Funis/etapas, workflows e smart lists só pela interface. A API cria contatos, oportunidades, campos e tags. A skill sabe a diferença e te dá a "receita de cliques" quando algo é UI-only.
  3. A deduplicação do GHL é fraca (só casa email OU telefone exato). A skill faz merge em memória antes de subir — uma pessoa real = um contato só.
  4. Telefone tem que ser E.164 (+55...). A skill normaliza e cria uma chave de dedup canônica.
  5. Planilhas vêm com linhas vazias de padding — a skill filtra antes de contar/importar.
  6. Nome só de fonte confiável (nada de "Lead #123" ou "@handle" como nome).
  7. Uma oportunidade por funil por pessoa (o GHL barra duplicada no mesmo funil).

Tudo isso está documentado dentro de ghl/SKILL.md — é o que o Claude lê pra agir.


📦 Instalação

Pré-requisitos

  • Claude Code instalado.
  • Python 3 (já vem no macOS/Linux).
  • Uma conta/subconta no GoHighLevel.

1. Baixe a skill

Clone o repositório (ou baixe o ZIP em Code → Download ZIP):

git clone https://github.com/LUIZOTAVIOENGENHARIADIGITAL/ghl-claude-skill.git
cd ghl-claude-skill

2. Copie a skill pra pasta do Claude

A pasta ghl/ é a skill. Copie pra ~/.claude/skills/:

mkdir -p ~/.claude/skills
cp -R ghl ~/.claude/skills/ghl

3. Pegue suas credenciais do GHL

Na sua subconta: Settings → Private Integrations → Create new integration. Dê os escopos de Contacts, Opportunities, Custom Fields e Tags. Copie o token (começa com pit-...) e o locationId da subconta.

4. Configure as variáveis de ambiente

Exporte no seu shell (ex.: ~/.zshrc ou ~/.bashrc):

export GHL_TOKEN="pit-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export GHL_LOCATION="seu-location-id"

Veja .env.example pro formato. Nunca comite suas credenciais.

5. Teste

python3 ~/.claude/skills/ghl/scripts/ghl.py whoami

Se aparecer sua location, seus funis e o total de contatos, está funcionando. ✅

6. Use no Claude

Abra o Claude Code e digite:

/ghl lista meus funis e campos

ou simplesmente peça em linguagem natural: "cria um contato no GHL pra ...".


🛠️ Uso direto do cliente (sem o Claude)

O scripts/ghl.py também roda sozinho:

python3 ghl/scripts/ghl.py whoami              # location + funis + total de contatos
python3 ghl/scripts/ghl.py pipelines           # funis e etapas (com IDs)
python3 ghl/scripts/ghl.py fields contact      # campos de contato
python3 ghl/scripts/ghl.py fields opportunity  # campos de oportunidade
python3 ghl/scripts/ghl.py tags                # tags da conta
python3 ghl/scripts/ghl.py count               # total de contatos
python3 ghl/scripts/ghl.py find email@ou.telefone

E como módulo Python, pra construir seus próprios importadores:

from ghl import upsert, create_opp, find_field, find_stage

c = upsert({"firstName": "Maria", "email": "maria@exemplo.com",
            "phone": "+5511999999999", "tags": ["status:lead", "source:youtube"]})
create_opp("Maria - Lead", "Funil de Vendas", "Novos Leads", "open",
           c["id"], value=997, source="youtube")

🔐 Segurança

  • Zero segredos no repositório. O código lê tudo de variáveis de ambiente.
  • Seu .env é ignorado pelo git (veja .gitignore).
  • O token é seu e dá acesso ao seu CRM — trate como senha.

📁 Estrutura do repositório

ghl-claude-skill/
├── ghl/                  # a skill (copie pra ~/.claude/skills/)
│   ├── SKILL.md          # instruções que o Claude lê pra operar o GHL
│   └── scripts/
│       └── ghl.py        # cliente Python da API v2 (UA correto, rate-limit, retry)
├── .env.example          # modelo de credenciais
├── .gitignore
├── LICENSE               # MIT
└── README.md

📺 Conteúdo

Quer aprender a estruturar CRM, funis e automações do jeito certo (dados > achismo)? Acompanhe o canal do Luiz Otávio — Engenheiro Digital no YouTube.

📄 Licença

MIT — use, modifique e distribua à vontade. Se ajudar, deixa uma ⭐ no repo!

Ver o original no GitHub

Bom para

Relacionados