HUBSPOT_CONTACT_CREATE - Criar Contato no HubSpot

O que é este Node?

O HUBSPOT_CONTACT_CREATE é o node responsável por criar novos contatos no HubSpot CRM, permitindo adicionar leads e clientes ao seu sistema de gestão de relacionamento diretamente de conversas no WhatsApp.

Por que este Node existe?

Centralizar informações de contatos é fundamental para uma estratégia de marketing e vendas eficaz. O HUBSPOT_CONTACT_CREATE existe para:

1. Captura Automatizada: Criar contatos automaticamente durante conversas no WhatsApp sem necessidade de entrada manual
2. Enriquecimento de Dados: Armazenar informações estruturadas sobre leads e clientes no HubSpot
3. Sincronização Omnichannel: Conectar conversas do WhatsApp ao ecossistema completo do HubSpot (marketing, vendas, suporte)
4. Base para Automação: Permitir que workflows e automações do HubSpot sejam acionados a partir de novos contatos

Como funciona internamente?

Quando o HUBSPOT_CONTACT_CREATE é executado, o sistema:

1. Recebe as propriedades: Coleta dados do contato (email, nome, telefone, empresa, etc.)
2. Processa variáveis: Substitui variáveis do contexto como {{user_email}} pelos valores reais
3. Monta o payload: Cria objeto properties com todos os campos do contato
4. Autentica na API: Usa Bearer Token (API Key) para autenticação
5. Faz requisição POST: Envia dados para /crm/v3/objects/contacts
6. Retorna ID do contato: HubSpot responde com o ID do contato criado e todas as propriedades
7. Armazena resultado: Salva resposta na variável configurada (padrão: hubspotResult)
8. Em caso de erro: Lança exceção com detalhes do erro para tratamento

Código interno (hubspot.executor.ts:47-59):

case 'create': {
  const properties = JSON.parse(this.replaceVariables(JSON.stringify(data.properties), context.variables));
  const response = await axios.post(
    baseUrl,
    { properties },
    { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }
  );
  return response.data;
}

Quando você DEVE usar este Node?

Use HUBSPOT_CONTACT_CREATE sempre que precisar de registrar novos contatos no HubSpot:

Casos de uso

1. Captura de leads via WhatsApp: Visitantes que iniciam conversa são automaticamente cadastrados como contatos
2. Formulários conversacionais: Bot coleta dados em formato de conversa e cria contato estruturado
3. Qualificação de prospects: Após série de perguntas, cria contato com informações de qualificação
4. Registro de clientes: Novos clientes são cadastrados no CRM durante processo de onboarding
5. Eventos e webinars: Participantes são registrados como contatos com tags e propriedades específicas

Quando NÃO usar HUBSPOT_CONTACT_CREATE

• Contato já existe: Use HUBSPOT_CONTACT_UPDATE para atualizar dados existentes
• Não tem certeza se existe: Use HUBSPOT_CONTACT_SEARCH primeiro para verificar
• Precisa buscar informações: Use HUBSPOT_CONTACT_GET para recuperar dados de um contato

Parâmetros Detalhados

properties (object, obrigatório)

O que é: Objeto contendo as propriedades do contato. O HubSpot aceita diversas propriedades padrão e customizadas.

Propriedades comuns: - email (string): Email do contato (recomendado como identificador único) - firstname (string): Primeiro nome - lastname (string): Sobrenome - phone (string): Telefone - company (string): Nome da empresa - website (string): Website - jobtitle (string): Cargo - lifecyclestage (string): Estágio no funil (lead, customer, etc.) - hs_lead_status (string): Status do lead

Padrão: Nenhum (obrigatório fornecer pelo menos um campo)

Flow completo para testar:

{
  "name": "Teste HubSpot - Criar Contato Básico",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Coletar Email",
        "parameters": {
          "message": "Qual é o seu email?",
          "variableName": "user_email"
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Coletar Nome",
        "parameters": {
          "message": "Qual é o seu nome?",
          "variableName": "user_name"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Criar Contato",
        "parameters": {
          "resource": "contacts",
          "operation": "create",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "properties": {
            "email": "{{user_email}}",
            "firstname": "{{user_name}}",
            "lifecyclestage": "lead",
            "hs_lead_status": "NEW"
          },
          "responseVariable": "hubspot_contact"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Contato criado com sucesso! ID: {{hubspot_contact.id}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "email_1" },
    { "source": "email_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 email válido (ex: teste@email.com) e depois seu nome (ex: João Silva). O sistema criará o contato no HubSpot e retornará o ID.

config.apiKey (string, obrigatório)

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

Como obter: 1. Acesse HubSpot → Settings → Integrations → Private Apps 2. Crie um novo Private App 3. Defina as permissões necessárias (crm.objects.contacts.write) 4. Copie o Access Token gerado

Exemplo: "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

responseVariable (string, opcional)

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

Padrão: "hubspotResult"

Exemplo: "contact_created", "new_contact", "hubspot_response"

Parâmetros

Campo	Tipo	Obrigatório	Descrição
resource	string	Sim	Deve ser "contacts"
operation	string	Sim	Deve ser "create"
config.apiKey	string	Sim	API Key do HubSpot (Private App Token)
properties	object	Sim	Propriedades do contato (email, firstname, etc.)
responseVariable	string	Não	Nome da variável para armazenar resultado (padrão: "hubspotResult")

Exemplo 1: Captura Simples de Lead

Objetivo: Criar contato com informações básicas coletadas em conversa

JSON para Importar

{
  "name": "HubSpot - Captura Básica de Lead",
  "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á! Vejo que você tem interesse em nossos serviços. Vamos começar!"
        }
      }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Qual é o seu email?",
          "variableName": "email"
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Nome",
        "parameters": {
          "message": "Qual é o seu nome?",
          "variableName": "nome"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Empresa",
        "parameters": {
          "message": "Qual é o nome da sua empresa?",
          "variableName": "empresa"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Criar Lead",
        "parameters": {
          "resource": "contacts",
          "operation": "create",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "properties": {
            "email": "{{email}}",
            "firstname": "{{nome}}",
            "company": "{{empresa}}",
            "lifecyclestage": "lead",
            "hs_lead_status": "NEW"
          }
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "Perfeito, {{nome}}! Suas informações foram registradas. Nossa equipe entrará em contato em breve!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "email_1" },
    { "source": "email_1", "target": "input_1" },
    { "source": "input_1", "target": "input_2" },
    { "source": "input_2", "target": "hubspot_1" },
    { "source": "hubspot_1", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Olá! Vejo que você tem interesse em nossos serviços. Vamos começar!
Sistema: Qual é o seu email?
Usuário: joao@empresa.com
Sistema: Qual é o seu nome?
Usuário: João Silva
Sistema: Qual é o nome da sua empresa?
Usuário: Empresa Tech LTDA
Sistema: Perfeito, João Silva! Suas informações foram registradas. Nossa equipe entrará em contato em breve!

Exemplo 2: Lead Qualificado com Dados Completos

Objetivo: Coletar informações detalhadas e criar contato qualificado no HubSpot

JSON para Importar

{
  "name": "HubSpot - Lead Qualificado Completo",
  "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": "Nome",
        "parameters": {
          "message": "Qual é o seu nome completo?",
          "variableName": "fullname"
        }
      }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Email corporativo:",
          "variableName": "email"
        }
      }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Telefone",
        "parameters": {
          "message": "Telefone para contato:",
          "variableName": "phone"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Empresa",
        "parameters": {
          "message": "Nome da empresa:",
          "variableName": "company"
        }
      }
    },
    {
      "id": "input_3",
      "type": "input",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Cargo",
        "parameters": {
          "message": "Seu cargo na empresa:",
          "variableName": "jobtitle"
        }
      }
    },
    {
      "id": "input_4",
      "type": "input",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Website",
        "parameters": {
          "message": "Website da empresa (opcional):",
          "variableName": "website"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 1500, "y": 100 },
      "data": {
        "label": "Criar Contato Qualificado",
        "parameters": {
          "resource": "contacts",
          "operation": "create",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "properties": {
            "email": "{{email}}",
            "firstname": "{{fullname}}",
            "phone": "{{phone}}",
            "company": "{{company}}",
            "jobtitle": "{{jobtitle}}",
            "website": "{{website}}",
            "lifecyclestage": "marketingqualifiedlead",
            "hs_lead_status": "IN_PROGRESS",
            "leadsource": "WhatsApp"
          },
          "responseVariable": "contact_data"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1700, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "Obrigado pelas informações, {{fullname}}! Seu perfil foi criado e nossa equipe de vendas entrará em contato em até 24h."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "email_1" },
    { "source": "email_1", "target": "phone_1" },
    { "source": "phone_1", "target": "input_2" },
    { "source": "input_2", "target": "input_3" },
    { "source": "input_3", "target": "input_4" },
    { "source": "input_4", "target": "hubspot_1" },
    { "source": "hubspot_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Qual é o seu nome completo?
Usuário: Maria Santos
Sistema: Email corporativo:
Usuário: maria@techcorp.com
Sistema: Telefone para contato:
Usuário: 11987654321
Sistema: Nome da empresa:
Usuário: TechCorp Brasil
Sistema: Seu cargo na empresa:
Usuário: Diretora de Marketing
Sistema: Website da empresa (opcional):
Usuário: www.techcorp.com.br
Sistema: Obrigado pelas informações, Maria Santos! Seu perfil foi criado e nossa equipe de vendas entrará em contato em até 24h.

Exemplo 3: Contato com Propriedades Personalizadas

Objetivo: Criar contato usando propriedades customizadas do HubSpot

JSON para Importar

{
  "name": "HubSpot - Contato com Props Customizadas",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Email",
        "parameters": {
          "message": "Email:",
          "variableName": "email"
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Nome",
        "parameters": {
          "message": "Nome:",
          "variableName": "name"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Produto Interesse",
        "parameters": {
          "message": "Qual produto interessa? (Premium/Standard/Basic)",
          "variableName": "product"
        }
      }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Budget",
        "parameters": {
          "message": "Budget mensal disponível (R$):",
          "variableName": "budget",
          "min": 0
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Criar com Props Custom",
        "parameters": {
          "resource": "contacts",
          "operation": "create",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "properties": {
            "email": "{{email}}",
            "firstname": "{{name}}",
            "lifecyclestage": "lead",
            "product_interest": "{{product}}",
            "monthly_budget": "{{budget}}",
            "lead_source": "WhatsApp Bot",
            "contact_priority": "High",
            "campaign_name": "Q1-2025-Inbound"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "Registrado! Produto: {{product}} | Budget: R${{budget}}. Você receberá uma proposta personalizada em breve."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "email_1" },
    { "source": "email_1", "target": "input_1" },
    { "source": "input_1", "target": "input_2" },
    { "source": "input_2", "target": "number_1" },
    { "source": "number_1", "target": "hubspot_1" },
    { "source": "hubspot_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Email:
Usuário: carlos@startup.com
Sistema: Nome:
Usuário: Carlos Mendes
Sistema: Qual produto interessa? (Premium/Standard/Basic)
Usuário: Premium
Sistema: Budget mensal disponível (R$):
Usuário: 5000
Sistema: Registrado! Produto: Premium | Budget: R$5000. Você receberá uma proposta personalizada em breve.

Resposta do Node

{
  "id": "12345678901",
  "properties": {
    "createdate": "2025-01-15T10:30:00.000Z",
    "email": "joao@empresa.com",
    "firstname": "João Silva",
    "hs_object_id": "12345678901",
    "lastmodifieddate": "2025-01-15T10:30:00.000Z",
    "lifecyclestage": "lead"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "archived": false
}

Campos retornados: - id: ID único do contato no HubSpot - properties: Todas as propriedades do contato (incluindo timestamps) - createdAt: Data/hora de criação - updatedAt: Data/hora da última atualização - archived: Se o contato está arquivado (sempre false ao criar)

Boas Práticas

✅ SIM:

• Sempre inclua email (é o identificador único mais importante no HubSpot)
• Use validação de email com node EMAIL antes de criar o contato
• Use validação de telefone com node PHONE para garantir formato correto
• Configure lifecyclestage apropriado (lead, marketingqualifiedlead, salesqualifiedlead, etc.)
• Registre a origem do lead em propriedade como "leadsource" ou custom field
• Use propriedades customizadas para informações específicas do seu negócio
• Armazene o ID retornado para futuras atualizações ou associações
• Trate erros de duplicação (email já existe) com CONDITION

❌ NÃO:

• Criar contatos sem email (HubSpot aceita, mas dificulta gestão)
• Criar duplicatas - sempre busque antes se não tiver certeza
• Usar valores hardcoded - sempre use variáveis do contexto
• Ignorar erros da API - sempre trate falhas de autenticação
• Criar contato sem contexto mínimo (pelo menos nome + email)
• Esquecer de registrar origem/fonte do contato para analytics
• Enviar dados sensíveis em propriedades sem considerar privacidade

Dicas

💡 Dica 1: Configure um flow de verificação usando HUBSPOT_CONTACT_SEARCH antes de criar, para evitar duplicatas. Use o email como filtro de busca.

💡 Dica 2: Combine com node AI para extrair automaticamente nome, empresa e outras informações de uma mensagem livre do usuário antes de criar o contato.

💡 Dica 3: Use propriedades customizadas para rastrear informações específicas como produto de interesse, origem da campanha, prioridade, etc.

💡 Dica 4: Após criar o contato, use HUBSPOT_DEAL_CREATE para criar uma oportunidade associada, construindo assim um pipeline completo.

💡 Dica 5: Configure workflows no HubSpot para serem acionados quando novos contatos são criados via WhatsApp (usando propriedade custom como trigger).

Próximos Nodes

→ HUBSPOT_CONTACT_UPDATE - Atualizar dados de contato existente → HUBSPOT_CONTACT_GET - Buscar informações de um contato específico → HUBSPOT_CONTACT_SEARCH - Buscar contatos por filtros → HUBSPOT_DEAL_CREATE - Criar oportunidade associada ao contato