Pular para o conteúdo
Triadeflow Docs

Integração GoHighLevel (GHL)

Como integrar agentes Triadeflow com GoHighLevel CRM. GHL é o CRM padrão para clientes com necessidades complexas, agências revendendo serviço, e operações em escala.

Quando usar GHL

  • Cliente é agência ou tem múltiplas operações
  • Precisa de calendário nativo, automações avançadas, snapshots
  • Precisa de A2P 10DLC compliance (US)
  • Volume alto de mensagens (>50k/mês)
  • White-label SaaS desejado

Para clientes brasileiros simples e PMEs, Kommo costuma ser melhor escolha.

Provider de mensageria

GHL usa Stevo como provider WhatsApp (WhatsApp Business API oficial integrado ao GHL). Detalhes em .claude/integrations/stevo.md.

Arquitetura GHL

GHL tem hierarquia de 3 níveis:

Agency (Triadeflow ou parceira)
└── Sub-Account (cliente final, ex: USA Salus)
    ├── Pipelines
    ├── Funnels
    ├── Calendars
    ├── Workflows
    └── Custom Values

Quando criar tenant em GHL, normalmente é uma sub-account dentro da agência da Triadeflow ou de uma parceira.

Setup do tenant

1. Acessos

  • Location ID (sub-account ID)
  • API Key (location-level, não agency-level para isolamento)
  • Pipeline ID e Stage IDs
  • Calendar IDs (se agendamento)
  • Custom Field IDs

2. Pipeline standard Triadeflow

Replicar estrutura similar ao Kommo:

crm:
  type: ghl
  location_id: LOC_123ABC
  api_token: ${TENANT_GHL_TOKEN}
  pipeline_id: PIPE_xyz
  stages:
    inbound: stage_001
    qualificado: stage_002
    agendado: stage_003
    convertido: stage_004
    perdido: stage_005

3. Custom Fields

GHL tem dois tipos:

  • Contact Custom Fields: dados do contato
  • Opportunity Custom Fields: dados da oportunidade no funil

Criar via API ou UI, anotar IDs:

crm:
  contact_fields:
    convenio: "abc-123"
    cidade: "abc-456"
  opportunity_fields:
    valor_estimado: "xyz-111"
    motivo_perda: "xyz-222"

4. Calendar (se agent-agendamento)

GHL tem sistema próprio de calendário. Configurar:

  • Calendar ID
  • Slot duration (ex: 30min)
  • Slot interval
  • Available hours
  • Buffer time
  • Timezone
calendar:
  type: ghl_native
  calendar_id: CAL_xyz
  slot_duration_min: 30
  buffer_min: 10
  advance_booking_days: 30

5. Workflows GHL para automação reversa

Workflow GHL pode ser triggered pelo agente para:

  • Enviar email de confirmação
  • Atribuir tag
  • Notificar humano via SMS
  • Disparar sequência de nurturing se lead esfria

Padrão: agente cria workflow trigger via API quando ação relevante acontece.

Operações comuns no código

Criar contato + opportunity

from triadeflow_core.crm.ghl import GHLClient


client = GHLClient(config.crm)


# Cria contato
contact_id = await client.create_contact(
    name=user_name,
    phone=user_phone,
    custom_fields={"abc-123": "Bradesco"},
    tags=["agent_sdr", "whatsapp_inbound"]
)


# Cria opportunity no pipeline
opp_id = await client.create_opportunity(
    contact_id=contact_id,
    pipeline_id=config.crm.pipeline_id,
    stage_id=config.crm.stages["inbound"],
    monetary_value=2500,  # estimado
    custom_fields={"xyz-111": 2500}
)

Mover stage

await client.move_opportunity(
    opportunity_id=opp_id,
    stage_id=config.crm.stages["qualificado"]
)

Disparar workflow

await client.trigger_workflow(
    workflow_id="wf_envia_link_agendamento",
    contact_id=contact_id,
)

Booking via calendar nativo

slot = await client.find_available_slot(
    calendar_id=config.calendar.calendar_id,
    after=datetime.now(),
    duration_min=30,
)


booking = await client.create_appointment(
    calendar_id=config.calendar.calendar_id,
    contact_id=contact_id,
    start_time=slot.start,
    title="Avaliação inicial - {nome}",
    notes="Agendado via WhatsApp pelo agente"
)

A2P 10DLC compliance (clientes US)

Para tenants nos EUA enviando SMS, precisa registro 10DLC:

  1. Brand registration (CIK ou DUNS)
  2. Campaign registration (use case, sample messages)
  3. CNAM (Caller ID name) verification
  4. Voice Integrity setup
  5. Terms of Service em URL pública

Documentação completa: caso real do USA Salus está documentado em .claude/examples/compliance/usa-salus-a2p10dlc.md.

Erros comuns

API rate limit

GHL limita ~100 req/min por location. Throttle automático no client.

Custom field não aparece

Custom fields levam alguns segundos pra propagar após criação. Cache localmente o mapping ID → name.

Token de location vs agency

Para operações de tenant, sempre use location-level token. Agency-level tem permissão demais e expõe outros tenants.

Stages renomeados

Cliente às vezes renomeia stages. Use IDs no código, nunca nomes.

Snapshots GHL

Snapshots são templates pré-configurados de funnels, workflows e campaigns. Triadeflow tem snapshots prontos para cada tipo de agente:

  • triadeflow-sdr-snapshot.zip
  • triadeflow-suporte-snapshot.zip
  • triadeflow-agendamento-snapshot.zip

Aplicar snapshot acelera setup novo em ~70%. Hospedados em Google Drive da Triadeflow.

Marketplace App (futuro)

Existe planejamento para construir Triadeflow App no GHL Marketplace. Vantagens:

  • Cliente instala em 1 clique
  • Renovação automática (revenue share com GHL)
  • Visibilidade no marketplace

Status atual: backlog (Tier 4 prioridade).

Referências internas

  • USA Salus — caso completo A2P 10DLC documentado
  • Grupo Camarmo — proposta WhatsApp Official + GHL
  • Talentus Digital — agência usando GHL como white-label

Detalhes em .claude/examples/integrations/.

Versão: 1.0