HubSpot CRM Integration - Lumina Flow Builder

Visão Geral

A integração do HubSpot CRM no Lumina Flow Builder permite gerenciar completamente seu CRM diretamente de conversas no WhatsApp. Com 23 operações distribuídas em 4 recursos principais, você pode automatizar todo o ciclo de vendas e atendimento.

Recursos Disponíveis

1. Contacts (Contatos) - 6 operações

Gerencie contatos (leads, prospects, clientes) no HubSpot:

• CONTACT_CREATE - Criar novo contato
• CONTACT_GET - Buscar contato por ID
• CONTACT_UPDATE - Atualizar dados do contato
• CONTACT_DELETE - Excluir contato (lixeira 90 dias)
• CONTACT_SEARCH - Buscar contatos por filtros
• CONTACT_LIST - Listar contatos (sem filtros)

2. Deals (Negócios/Oportunidades) - 6 operações

Gerencie oportunidades de venda e pipeline:

• DEAL_CREATE - Criar nova oportunidade
• DEAL_GET - Buscar deal por ID
• DEAL_UPDATE - Atualizar deal (avançar pipeline, mudar valor)
• DEAL_DELETE - Excluir deal
• DEAL_SEARCH - Buscar deals por filtros
• DEAL_LIST - Listar deals

3. Companies (Empresas) - 6 operações

Gerencie empresas e contas B2B:

• COMPANY_CREATE - Criar nova empresa
• COMPANY_GET - Buscar empresa por ID
• COMPANY_UPDATE - Atualizar dados da empresa
• COMPANY_DELETE - Excluir empresa
• COMPANY_SEARCH - Buscar empresas por filtros
• COMPANY_LIST - Listar empresas

4. Tickets (Suporte) - 5 operações

Gerencie tickets de atendimento e suporte:

• TICKET_CREATE - Criar ticket de suporte
• TICKET_GET - Buscar ticket por ID
• TICKET_UPDATE - Atualizar ticket
• TICKET_DELETE - Excluir ticket
• TICKET_LIST - Listar tickets

Configuração Inicial

1. Obter API Key (Private App Token)

1. Acesse seu HubSpot → Settings (engrenagem no topo)
2. No menu esquerdo: Integrations → Private Apps
3. Clique em Create a private app
4. Nomeie sua app (ex: "Lumina WhatsApp Bot")
5. Em Scopes, defina as permissões necessárias:
6. crm.objects.contacts.read e .write
7. crm.objects.deals.read e .write
8. crm.objects.companies.read e .write
9. crm.objects.tickets.read e .write
10. Clique em Create app
11. Copie o Access Token gerado - use este token como apiKey

2. Usar no Flow Builder

Em todos os nodes HubSpot, configure:

{
  "config": {
    "apiKey": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Dica: Armazene o token em variável de ambiente ou variable node para reutilização.

Casos de Uso Práticos

1. Captura Automática de Leads via WhatsApp

Fluxo: START → Coleta Email → Coleta Nome/Empresa → HUBSPOT_CONTACT_CREATE → HUBSPOT_DEAL_CREATE → Confirmação → END

Resultado: Lead capturado e oportunidade criada automaticamente quando cliente manifesta interesse.

2. Atendimento com Histórico Completo

Fluxo: START → HUBSPOT_CONTACT_SEARCH (por email/telefone) → HUBSPOT_CONTACT_GET → Personalizar mensagens com dados → END

Resultado: Atendente tem contexto completo do cliente antes mesmo de responder.

3. Pipeline Conversacional

Fluxo: START → HUBSPOT_DEAL_SEARCH (deals do contato) → HUBSPOT_DEAL_GET → Mostrar status → HUBSPOT_DEAL_UPDATE (avançar estágio) → END

Resultado: Cliente pode acompanhar e avançar próprio deal via WhatsApp.

4. Sistema de Tickets Automatizado

Fluxo: START → Coleta problema → HUBSPOT_TICKET_CREATE → Envia protocolo → END

Resultado: Cada solicitação vira ticket rastreável no HubSpot.

5. Qualificação de Lead com IA

Fluxo: START → AI_AGENT (conversa livre) → Extrai dados → HUBSPOT_CONTACT_CREATE + HUBSPOT_COMPANY_CREATE + HUBSPOT_DEAL_CREATE → END

Resultado: Bot qualifica lead conversando naturalmente e registra tudo estruturado.

Workflows Avançados

Workflow 1: Lead Capture Completo com Associações

START
  ↓
EMAIL (coletar email)
  ↓
HUBSPOT_CONTACT_SEARCH (verificar se existe)
  ↓
CONDITION (existe?)
  ├─ SIM → HUBSPOT_CONTACT_GET (carregar dados)
  └─ NÃO → Coletar dados → HUBSPOT_CONTACT_CREATE
  ↓
Coletar empresa
  ↓
HUBSPOT_COMPANY_CREATE (criar empresa)
  ↓
HUBSPOT_DEAL_CREATE (criar deal associado ao contact e company)
  ↓
MESSAGE (confirmar com protocolo)
  ↓
END

Workflow 2: Dashboard Conversacional

START
  ↓
HUBSPOT_CONTACT_LIST (limit: 5)
  ↓
HUBSPOT_DEAL_LIST (limit: 5)
  ↓
HUBSPOT_TICKET_LIST (limit: 5)
  ↓
MESSAGE ("📊 Dashboard: X contatos, Y deals, Z tickets")
  ↓
END

Workflow 3: Atualização de Pipeline Automática

START
  ↓
HUBSPOT_DEAL_SEARCH (deals em estágio "Proposal Sent")
  ↓
LOOP (cada deal encontrado)
  ↓
MESSAGE ("Deal X está em proposta. Foi fechado? SIM/NÃO")
  ↓
CONDITION (resposta == "SIM")
  ├─ SIM → HUBSPOT_DEAL_UPDATE (dealstage: "closedwon")
  └─ NÃO → próximo deal
  ↓
END LOOP
  ↓
END

Propriedades Importantes

Contacts

Propriedade	Tipo	Descrição
email	string	Email (identificador único recomendado)
firstname	string	Primeiro nome
lastname	string	Sobrenome
phone	string	Telefone
company	string	Nome da empresa
jobtitle	string	Cargo
lifecyclestage	string	Estágio: lead, marketingqualifiedlead, salesqualifiedlead, customer
hs_lead_status	string	Status: NEW, OPEN, IN_PROGRESS, CONNECTED

Deals

Propriedade	Tipo	Descrição
dealname	string	Nome do negócio
amount	number	Valor em dinheiro
dealstage	string	Estágio no pipeline
closedate	date	Data prevista de fechamento (YYYY-MM-DD)
pipeline	string	ID do pipeline (default = "default")
hubspot_owner_id	string	ID do vendedor responsável

Companies

Propriedade	Tipo	Descrição
name	string	Nome da empresa
domain	string	Domínio/website (para deduplicação)
industry	string	Setor/indústria
phone	string	Telefone
city	string	Cidade
state	string	Estado

Tickets

Propriedade	Tipo	Descrição
subject	string	Assunto do ticket
content	string	Descrição/corpo do ticket
hs_ticket_priority	string	Prioridade: LOW, MEDIUM, HIGH
hs_pipeline_stage	string	Estágio do ticket

Operadores de Filtro (Search)

Ao usar operações SEARCH, você pode usar estes operadores:

Operador	Descrição	Exemplo
EQ	Igual a (equals)	"operator": "EQ", "value": "joao@email.com"
NEQ	Diferente de (not equal)	"operator": "NEQ", "value": "closed"
LT	Menor que (less than)	"operator": "LT", "value": "1000"
GT	Maior que (greater than)	"operator": "GT", "value": "5000"
LTE	Menor ou igual	"operator": "LTE", "value": "10000"
GTE	Maior ou igual	"operator": "GTE", "value": "1000"
CONTAINS	Contém	"operator": "CONTAINS", "value": "tech"
NOT_CONTAINS	Não contém	"operator": "NOT_CONTAINS", "value": "spam"

Exemplo de filtro composto:

{
  "filters": [
    {
      "filters": [
        {
          "propertyName": "amount",
          "operator": "GT",
          "value": "10000"
        },
        {
          "propertyName": "dealstage",
          "operator": "EQ",
          "value": "presentationscheduled"
        }
      ]
    }
  ]
}

Boas Práticas Gerais

✅ SEMPRE FAÇA

1. Valide antes de criar: Use SEARCH para verificar se contato/empresa já existe
2. Use variáveis: Nunca use IDs ou tokens hardcoded no JSON
3. Confirme operações críticas: Delete sempre deve ter confirmação dupla
4. Armazene IDs: Salve IDs retornados para operações futuras
5. Trate erros: Use CONDITION para verificar se operação foi bem-sucedida
6. Associe registros: Vincule contacts a companies e deals para melhor organização
7. Registre origem: Use propriedade customizada para rastrear que lead veio do WhatsApp
8. Implemente paginação: Para listagens grandes, use limit apropriado

❌ NUNCA FAÇA

1. Criar duplicatas: Sempre busque antes de criar novo registro
2. Expor tokens: Nunca compartilhe API Key em logs ou mensagens
3. Ignorar erros: Sempre implemente fluxo alternativo para falhas
4. Atualizar sem verificar: Busque dados atuais antes de atualizar
5. Excluir sem confirmar: Delete é operação séria, sempre confirme
6. Listar tudo sem controle: Use filtros e limits para não sobrecarregar
7. Assumir que dados existem: Sempre valide antes de acessar propriedades
8. Usar operações síncronas em loop: Pode gerar timeout

Tratamento de Erros Comuns

Erro 401: Unauthorized

Causa: API Key inválida ou sem permissões Solução: Verifique token e scopes na Private App

Erro 404: Not Found

Causa: ID não existe ou foi deletado Solução: Use CONDITION para verificar se resultado existe antes de usar

Erro 409: Conflict

Causa: Tentando criar registro com email/domínio duplicado Solução: Use SEARCH antes de CREATE para evitar duplicatas

Erro 429: Rate Limit

Causa: Muitas requisições em curto período Solução: Implemente DELAY entre requisições em massa

Exemplo Completo: CRM Conversacional Full-Stack

Este exemplo demonstra um fluxo completo de captura, qualificação e criação de oportunidade:

{
  "name": "HubSpot - CRM Completo WhatsApp",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Boas-vindas",
        "parameters": {
          "message": "Olá! Vamos cadastrar suas informações no nosso sistema."
        }
      }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Qual é o seu email?",
          "variableName": "email"
        }
      }
    },
    {
      "id": "hubspot_search_1",
      "type": "hubspot",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Verificar Email",
        "parameters": {
          "resource": "contacts",
          "operation": "search",
          "config": { "apiKey": "{{hubspot_api_key}}" },
          "filters": [
            {
              "filters": [
                {
                  "propertyName": "email",
                  "operator": "EQ",
                  "value": "{{email}}"
                }
              ]
            }
          ],
          "limit": 1,
          "responseVariable": "existing_contact"
        }
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Email Existe?",
        "parameters": {
          "variable": "{{existing_contact.total}}",
          "operator": "greater_than",
          "value": "0"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1100, "y": 50 },
      "data": {
        "label": "Cliente Existente",
        "parameters": {
          "message": "Olá {{existing_contact.results.0.properties.firstname}}! Bem-vindo de volta!"
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 1100, "y": 150 },
      "data": {
        "label": "Nome",
        "parameters": {
          "message": "Qual é o seu nome?",
          "variableName": "name"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 1300, "y": 150 },
      "data": {
        "label": "Empresa",
        "parameters": {
          "message": "Nome da empresa:",
          "variableName": "company"
        }
      }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 1500, "y": 150 },
      "data": {
        "label": "Telefone",
        "parameters": {
          "message": "Telefone:",
          "variableName": "phone"
        }
      }
    },
    {
      "id": "hubspot_contact_1",
      "type": "hubspot",
      "position": { "x": 1700, "y": 150 },
      "data": {
        "label": "Criar Contato",
        "parameters": {
          "resource": "contacts",
          "operation": "create",
          "config": { "apiKey": "{{hubspot_api_key}}" },
          "properties": {
            "email": "{{email}}",
            "firstname": "{{name}}",
            "phone": "{{phone}}",
            "company": "{{company}}",
            "lifecyclestage": "lead",
            "hs_lead_status": "NEW",
            "leadsource": "WhatsApp"
          },
          "responseVariable": "new_contact"
        }
      }
    },
    {
      "id": "hubspot_company_1",
      "type": "hubspot",
      "position": { "x": 1900, "y": 150 },
      "data": {
        "label": "Criar Empresa",
        "parameters": {
          "resource": "companies",
          "operation": "create",
          "config": { "apiKey": "{{hubspot_api_key}}" },
          "properties": {
            "name": "{{company}}",
            "lifecyclestage": "lead"
          },
          "responseVariable": "new_company"
        }
      }
    },
    {
      "id": "input_3",
      "type": "input",
      "position": { "x": 2100, "y": 150 },
      "data": {
        "label": "Interesse",
        "parameters": {
          "message": "Qual produto/serviço interessa?",
          "variableName": "produto"
        }
      }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 2300, "y": 150 },
      "data": {
        "label": "Valor",
        "parameters": {
          "message": "Qual o budget estimado (R$)?",
          "variableName": "budget",
          "min": 0,
          "decimals": 2
        }
      }
    },
    {
      "id": "hubspot_deal_1",
      "type": "hubspot",
      "position": { "x": 2500, "y": 150 },
      "data": {
        "label": "Criar Deal",
        "parameters": {
          "resource": "deals",
          "operation": "create",
          "config": { "apiKey": "{{hubspot_api_key}}" },
          "properties": {
            "dealname": "WhatsApp - {{produto}} - {{company}}",
            "amount": "{{budget}}",
            "dealstage": "appointmentscheduled",
            "pipeline": "default"
          },
          "associations": [
            {
              "to": { "id": "{{new_contact.id}}" },
              "types": [
                {
                  "associationCategory": "HUBSPOT_DEFINED",
                  "associationTypeId": 3
                }
              ]
            },
            {
              "to": { "id": "{{new_company.id}}" },
              "types": [
                {
                  "associationCategory": "HUBSPOT_DEFINED",
                  "associationTypeId": 5
                }
              ]
            }
          ],
          "responseVariable": "new_deal"
        }
      }
    },
    {
      "id": "merge_1",
      "type": "merge",
      "position": { "x": 2700, "y": 100 },
      "data": { "label": "Convergir" }
    },
    {
      "id": "message_3",
      "type": "message",
      "position": { "x": 2900, "y": 100 },
      "data": {
        "label": "Confirmação Final",
        "parameters": {
          "message": "✅ TUDO PRONTO!\n\n📋 Contato: {{new_contact.id}}\n🏢 Empresa: {{new_company.id}}\n💰 Deal: {{new_deal.id}}\n\nNossa equipe entrará em contato em até 24h!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 3100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "email_1" },
    { "source": "email_1", "target": "hubspot_search_1" },
    { "source": "hubspot_search_1", "target": "condition_1" },
    { "source": "condition_1", "target": "message_2", "label": "true" },
    { "source": "condition_1", "target": "input_1", "label": "false" },
    { "source": "message_2", "target": "merge_1" },
    { "source": "input_1", "target": "input_2" },
    { "source": "input_2", "target": "phone_1" },
    { "source": "phone_1", "target": "hubspot_contact_1" },
    { "source": "hubspot_contact_1", "target": "hubspot_company_1" },
    { "source": "hubspot_company_1", "target": "input_3" },
    { "source": "input_3", "target": "number_1" },
    { "source": "number_1", "target": "hubspot_deal_1" },
    { "source": "hubspot_deal_1", "target": "merge_1" },
    { "source": "merge_1", "target": "message_3" },
    { "source": "message_3", "target": "end_1" }
  ]
}

Recursos Adicionais

• Documentação oficial da API HubSpot
• HubSpot CRM Objects
• HubSpot Private Apps
• HubSpot Rate Limits

Suporte

Para dúvidas sobre operações específicas, consulte a documentação individual de cada node nos links acima.

Para problemas com a API HubSpot, consulte HubSpot Developer Forum.

---

Total de Operações: 23 Arquivo: /home/zielinski/develop/gptapi/src/whatsapp-flows/node-executors/hubspot.executor.ts Última atualização: 2025-10-13