ghl-integration

GoHighLevel (GHL) API v2 Integration Skill

Desenvolvido por / Créditos: Rafa Martins (rafacpti@gmail.com)

Esta skill permite ao Hermes interagir com a API v2 do GoHighLevel por meio do utilitário local ghl_client.py e receber eventos instantâneos com ghl_webhook_server.py.

---

⚠️ REGRA DE GOVERNANÇA E HUMAN-IN-THE-LOOP (CRÍTICO)

Para proteção contra loops e destruição de dados acidentais no CRM:

1. PROIBIDO DELETAR contatos, oportunidades, mensagens, tarefas ou notas de forma autônoma.
2. PROIBIDO DESATIVAR OU ALTERAR Workflows/Automações estruturais no GHL.
3. Se houver comandos para destruição de dados ou cancelamento em lote, o Hermes DEVE pausar e solicitar autorização explícita do usuário humano primeiro.
4. Operações de exclusão na API devem sempre usar confirmação manual (Human-in-the-Loop).

---

🚨 PITFALL: mensagens de broadcast de TERCEIROS contaminam relatórios

As conversas retornadas por --action unanswered incluem listas de transmissão, grupos e comunidades que o próprio usuário assina (ex.: comunidades de API/dev, avisos de "estamos ao vivo", convites para imersões/webinars). Elas trazem URLs promocionais de terceiros.

Se um relatório automatizado (cron de auditoria) extrai URLs dessas conversas e as mistura com as URLs reais dos criativos de anúncio, cria um ativo fantasma que parece campanha ativa. Isso já aconteceu e gerou o falso positivo "Evolution Imersão" em relatório de Meta Ads.

Regras:

1. URLs vindas de conversas do GHL nunca entram em tabelas de "Auditoria de Landing Pages" ou de destinos de anúncio. Essas tabelas só aceitam URLs extraídas de adcreatives.
2. Se links de conversas forem relevantes, coloque-os em seção separada rotulada como "links recebidos de terceiros (não são destinos de anúncio)".
3. Antes de tratar um remetente como lead, verifique se é pessoa física: phone com formato +120363330319945564 (muito longo, sem DDI válido) indica grupo/broadcast, não contato.
4. Ao investigar de onde saiu um nome estranho em relatório, faça grep primeiro nos outputs do cron e nos dumps de sessão — antes de acusar a plataforma de anúncios:

   grep -i -n -E "" /root/.hermes/cron/output/*.txt
   grep -rhoi -E ".{0,300}" /root/.hermes/sessions/*.json | sort -u | head
   

---

⚡ Variáveis de Ambiente Necessárias (Adicionar ao .env ou config.yaml)

GHL_API_KEY=sua_location_api_key_aqui
GHL_LOCATION_ID=seu_location_id_aqui
GHL_WEBHOOK_PORT=8080
MANAGER_PHONE=telefone_do_gestor_para_alertas

---

🟢 WEBHOOK EM TEMPO REAL: RECEBER LEADS

Para receber leads de forma síncrona sem colisões multi-conta:

1. Inicie o servidor HTTP interno do Hermes:

   python3 /root/.hermes/metaads/ghl_webhook_server.py
   

2. No Workflow do GoHighLevel, aponte a ação HTTP POST de Webhook para: http://IP_DO_HERMES:GHL_WEBHOOK_PORT/webhook/

---

🛠️ Comandos de Execução no Terminal

O agente executa estas tarefas chamando diretamente o script /root/.hermes/metaads/ghl_client.py via Python:

1. Enviar Mensagem Direta (E-mail, SMS ou WhatsApp via STEVO)

# Enviar E-mail
python3 /root/.hermes/metaads/ghl_client.py --action send_msg --contact-id  --msg-type "Email" --subject "Sua Proposta Chegou!" --message "Olá, segue aqui a sua proposta comercial."

# Enviar SMS ou WhatsApp
python3 /root/.hermes/metaads/ghl_client.py --action send_msg --contact-id  --msg-type "WhatsApp" --message "Olá! Vimos seu cadastro no Instagram. Como podemos te ajudar?"

2. Encontrar Leads Sem Resposta (Inbound pendentes)

python3 /root/.hermes/metaads/ghl_client.py --action unanswered

3. Mover Lead no Kanban (Mudar Etapa)

python3 /root/.hermes/metaads/ghl_client.py --action update_opp_stage --opp-id  --stage-id 

4. Criar Contato com Tags do Meta Ads

python3 /root/.hermes/metaads/ghl_client.py --action create_contact --email "exemplo@email.com" --name "João Silva" --phone "+551****9999" --tags "meta-ads"

---

💡 COMPORTAMENTOS CONHECIDOS & TROUBLESHOOTING

1. Diferença entre Conversation ID e Contact ID: Ao executar a listagem de leads sem resposta via --action unanswered, saiba que a chave "id" no payload de conversas representa o Conversation ID daquela conversa específica. No entanto, para enviar mensagens (--action send_msg) ou manipular o contato, é obrigatório passar o Contact ID (que vem sob a chave "contactId" no payload bruto do GHL). Sempre certifique-se de obter e usar o ID do contato e não o ID da conversa.
   • Header de Versão Obrigatório (Version: 2021-04-15): Ao fazer chamadas diretas REST para a API do LeadConnector/GHL (/conversations/search), utilize obrigatoriamente o header Version: 2021-04-15. O uso de versões mais recentes (como 2021-07-28) retorna payload vazio ({"conversations": []}).
   • Workaround via raw API / Helper Script: Para obter o contactId de cada conversa retornada pelo script, faça chamada direta utilizando obrigatoriamente a base da API v2 (https://services.leadconnectorhq.com — NUNCA utilize rest.gohighlevel.com legada, pois ela retorna 0 conversas nos endpoints v2). Para evitar erros de parsing de .env (como 401 Invalid JWT por aspas não tratadas), importe o cliente diretamente:

     import sys, requests
     sys.path.append('/root/.hermes/metaads')
     import ghl_client
     headers = ghl_client.get_headers()
     loc_id = ghl_client.GHL_LOCATION_ID
     url = f"{ghl_client.GHL_API_BASE}/conversations/search"
     params = {"locationId": loc_id, "limit": 30}
     res = requests.get(url, headers=headers, params=params)
     for conv in res.json().get("conversations", []):
         conv_id = conv.get("id")
         contact_id = conv.get("contactId")  # ← o campo correto
         name = conv.get("contactName")
         phone = conv.get("phone")
     

   • Ordenação Temporal de Mensagens (dateAdded): Ao consultar /conversations/{conv_id}/messages, as mensagens na lista podem vir desordenadas. Para identificar com certeza quem enviou a última mensagem (inbound vs outbound), ordene a lista por dateAdded (ISO 8601):

     sorted_msgs = sorted(msgs, key=lambda x: x.get("dateAdded", ""))
     last_msg = sorted_msgs[-1] if sorted_msgs else None
     

   • Notas sobre f-strings no terminal Python one-liner: Ao escrever -c one-liners Python com f-strings, evite backslashes dentro das chaves do f-string (sintaxe inválida no Python 3.11-). Use variáveis intermediárias:

     # ERRADO: print(f"{d.get(\"key\")}")
     # CERTO:
     val = d.get("key")
     print(f"{val}")
     

2. Triagem de Mensagens Sem Resposta: Para classificar leads obtidos via --action unanswered, utilize a taxonomia de triagem definida em references/unanswered_leads_triaging_patterns.md (classificando entre Faturamento, Notificação de Sistema, Erro de Integração ou Engajamento Ativo).
3. Queda de Conexão do Gateway (WhatsApp Inativo): Se o webhook ou cron relatar que o serviço "não está rodando" ou retornar tags do tipo [P-mon] papi_disconnected no campo de últimas mensagens, veja references/stevo-whatsapp.md para instruções de reconexão do QR Code.