Pular para conteúdo

HUBSPOT_CONTACT_GET - Buscar Contato no HubSpot

O que é este Node?

O HUBSPOT_CONTACT_GET é o node responsável por buscar informações detalhadas de um contato específico no HubSpot CRM usando seu ID, permitindo recuperar dados para personalização e decisões em flows.

Por que este Node existe?

Recuperar informações de contatos existentes é essencial para personalização e lógica condicional. O HUBSPOT_CONTACT_GET existe para:

  1. Personalização Avançada: Buscar dados do contato para criar experiências personalizadas na conversa
  2. Decisões Condicionais: Verificar propriedades do contato para direcionar o flow apropriadamente
  3. Enriquecimento de Contexto: Carregar histórico e informações para contexto completo
  4. Validação de Dados: Verificar se informações estão atualizadas antes de prosseguir

Como funciona internamente?

Quando o HUBSPOT_CONTACT_GET é executado, o sistema:

  1. Recebe o contactId: ID do contato a ser buscado
  2. Processa variáveis: Substitui {{contact_id}} pelo valor real do contexto
  3. Autentica na API: Usa Bearer Token (API Key) para autenticação
  4. Faz requisição GET: Busca dados em /crm/v3/objects/contacts/{contactId}
  5. Retorna dados completos: HubSpot responde com todas as propriedades do contato
  6. Armazena resultado: Salva resposta na variável configurada
  7. Em caso de erro: Lança exceção se contato não existir ou houver erro de autenticação

Código interno (hubspot.executor.ts:61-68): 

case 'get': {
  const contactId = this.replaceVariables(data.contactId, context.variables);
  const response = await axios.get(
    `${baseUrl}/${contactId}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );
  return response.data;
}

Quando você DEVE usar este Node?

Use HUBSPOT_CONTACT_GET sempre que precisar de recuperar dados de um contato existente:

Casos de uso

  1. Saudação personalizada: Buscar nome e informações do contato para cumprimentar adequadamente
  2. Verificação de status: Checar lifecycle stage ou status do lead antes de prosseguir
  3. Continuidade de conversa: Recuperar contexto de conversas anteriores
  4. Validação de elegibilidade: Verificar se contato atende critérios para oferta/promoção
  5. Atualização condicional: Buscar dados atuais antes de decidir se atualiza

Quando NÃO usar HUBSPOT_CONTACT_GET

  • Não tem o ID do contato: Use HUBSPOT_CONTACT_SEARCH para buscar por email ou outros campos
  • Precisa de múltiplos contatos: Use HUBSPOT_CONTACT_LIST ou HUBSPOT_CONTACT_SEARCH
  • Quer criar novo contato: Use HUBSPOT_CONTACT_CREATE

Parâmetros Detalhados

contactId (string, obrigatório)

O que é: ID único do contato no HubSpot. É o identificador numérico retornado ao criar ou buscar um contato.

Exemplo: "12345678901", "{{saved_contact_id}}", "{{hubspot_contact.id}}"

Flow completo para testar:

{
  "name": "Teste HubSpot - Buscar Contato por ID",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Pedir ID",
        "parameters": {
          "message": "Digite o ID do contato HubSpot:",
          "variableName": "contact_id"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Buscar Contato",
        "parameters": {
          "resource": "contacts",
          "operation": "get",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "contactId": "{{contact_id}}",
          "responseVariable": "contact_data"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Mostrar Dados",
        "parameters": {
          "message": "Contato encontrado!\n\nNome: {{contact_data.properties.firstname}}\nEmail: {{contact_data.properties.email}}\nEmpresa: {{contact_data.properties.company}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "hubspot_1" },
    { "source": "hubspot_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Digite um ID válido de contato do seu HubSpot. O sistema buscará e exibirá as informações.

config.apiKey (string, obrigatório)

O que é: API Key (Private App Token) do HubSpot para autenticação.

Como obter: 1. Acesse HubSpot → Settings → Integrations → Private Apps 2. Defina permissões: crm.objects.contacts.read 3. Copie o Access Token

responseVariable (string, opcional)

O que é: Nome da variável onde o resultado será armazenado.

Padrão: "hubspotResult"

Parâmetros

Campo Tipo Obrigatório Descrição
resource string Sim Deve ser "contacts"
operation string Sim Deve ser "get"
config.apiKey string Sim API Key do HubSpot
contactId string Sim ID do contato a buscar
responseVariable string Não Variável para armazenar resultado (padrão: "hubspotResult")

Exemplo 1: Saudação Personalizada com Dados do Contato

Objetivo: Buscar informações do contato e criar saudação personalizada

JSON para Importar

{
  "name": "HubSpot - Saudação Personalizada",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Definir Contact ID",
        "parameters": {
          "variableName": "my_contact_id",
          "value": "12345678901"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Buscar Contato",
        "parameters": {
          "resource": "contacts",
          "operation": "get",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "contactId": "{{my_contact_id}}",
          "responseVariable": "contact"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Saudação",
        "parameters": {
          "message": "Olá {{contact.properties.firstname}}! 👋\n\nVejo que você trabalha na {{contact.properties.company}}. Como posso ajudar hoje?"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "hubspot_1" },
    { "source": "hubspot_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Olá Maria! 👋

Vejo que você trabalha na TechCorp. Como posso ajudar hoje?

Exemplo 2: Verificar Status e Direcionar Flow

Objetivo: Buscar contato e direcionar conversa baseado em lifecycle stage

JSON para Importar

{
  "name": "HubSpot - Verificar Status do Lead",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Pedir ID",
        "parameters": {
          "message": "Digite seu ID de contato:",
          "variableName": "contact_id"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Buscar Status",
        "parameters": {
          "resource": "contacts",
          "operation": "get",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "contactId": "{{contact_id}}",
          "responseVariable": "contact"
        }
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Verificar Lifecycle",
        "parameters": {
          "variable": "{{contact.properties.lifecyclestage}}",
          "operator": "equals",
          "value": "customer"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 50 },
      "data": {
        "label": "Cliente",
        "parameters": {
          "message": "Olá {{contact.properties.firstname}}! Você já é nosso cliente. Como podemos melhorar sua experiência?"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 900, "y": 150 },
      "data": {
        "label": "Lead",
        "parameters": {
          "message": "Olá {{contact.properties.firstname}}! Vi que você demonstrou interesse. Gostaria de conhecer nossos produtos?"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "hubspot_1" },
    { "source": "hubspot_1", "target": "condition_1" },
    { "source": "condition_1", "target": "message_1", "label": "true" },
    { "source": "condition_1", "target": "message_2", "label": "false" },
    { "source": "message_1", "target": "end_1" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada (se cliente):

Sistema: Digite seu ID de contato:
Usuário: 12345678901
Sistema: Olá João! Você já é nosso cliente. Como podemos melhorar sua experiência?

Saída esperada (se lead):

Sistema: Digite seu ID de contato:
Usuário: 98765432109
Sistema: Olá Maria! Vi que você demonstrou interesse. Gostaria de conhecer nossos produtos?

Exemplo 3: Buscar e Atualizar Dados

Objetivo: Buscar contato, mostrar dados atuais e permitir atualização

JSON para Importar

{
  "name": "HubSpot - Buscar e Preparar Atualização",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "ID do Contato",
        "parameters": {
          "message": "ID do contato a consultar:",
          "variableName": "contact_id"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Buscar Dados Atuais",
        "parameters": {
          "resource": "contacts",
          "operation": "get",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "contactId": "{{contact_id}}",
          "responseVariable": "current_contact"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Mostrar Dados",
        "parameters": {
          "message": "📋 DADOS ATUAIS\n\nNome: {{current_contact.properties.firstname}}\nEmail: {{current_contact.properties.email}}\nEmpresa: {{current_contact.properties.company}}\nCargo: {{current_contact.properties.jobtitle}}\nTelefone: {{current_contact.properties.phone}}\n\nDeseja atualizar alguma informação?"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "hubspot_1" },
    { "source": "hubspot_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: ID do contato a consultar:
Usuário: 12345678901
Sistema: 📋 DADOS ATUAIS

Nome: Carlos
Email: carlos@empresa.com
Empresa: Startup XYZ
Cargo: CTO
Telefone: 11999887766

Deseja atualizar alguma informação?

Resposta do Node

{
  "id": "12345678901",
  "properties": {
    "createdate": "2025-01-10T08:00:00.000Z",
    "email": "joao@empresa.com",
    "firstname": "João",
    "lastname": "Silva",
    "phone": "11987654321",
    "company": "Empresa Tech",
    "jobtitle": "CEO",
    "website": "www.empresa.com",
    "lifecyclestage": "customer",
    "hs_lead_status": "CONNECTED",
    "lastmodifieddate": "2025-01-15T10:30:00.000Z"
  },
  "createdAt": "2025-01-10T08:00:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "archived": false
}

Boas Práticas

✅ SIM:

  • Sempre armazene o resultado em variável nomeada apropriadamente
  • Use CONDITION após buscar para verificar se dados existem
  • Acesse propriedades usando {{variable.properties.fieldname}}
  • Implemente tratamento de erro caso contato não seja encontrado
  • Cache o resultado se for usar múltiplas vezes no mesmo flow
  • Use para personalização de mensagens e decisões condicionais

❌ NÃO:

  • Buscar contato repetidamente - armazene resultado e reutilize
  • Assumir que propriedades sempre existem - verifique antes de usar
  • Usar IDs hardcoded - sempre use variáveis
  • Ignorar erros 404 (contato não encontrado)
  • Expor informações sensíveis do contato sem cuidado

Dicas

💡 Dica 1: Combine com CONDITION para verificar se hubspotResult.id existe antes de tentar usar as propriedades, evitando erros.

💡 Dica 2: Use o resultado para alimentar nodes de decisão (SWITCH, CONDITION) baseados em lifecycle stage, status, ou propriedades customizadas.

💡 Dica 3: Armazene o ID do contato em banco de dados local associado ao número do WhatsApp para futuras consultas rápidas.

💡 Dica 4: Use as propriedades retornadas para pré-preencher formulários ou confirmar dados com o usuário antes de atualizar.

💡 Dica 5: Combine com HUBSPOT_DEAL_LIST ou outras operações para criar dashboards conversacionais completos.

Próximos Nodes

→ HUBSPOT_CONTACT_UPDATE - Atualizar dados do contato → HUBSPOT_CONTACT_SEARCH - Buscar contatos por filtros → HUBSPOT_CONTACT_DELETE - Excluir contato → HUBSPOT_DEAL_CREATE - Criar deal associado ao contato