Pular para conteúdo

HUBSPOT_CONTACT_UPDATE - Atualizar Contato no HubSpot

O que é este Node?

O HUBSPOT_CONTACT_UPDATE é o node responsável por atualizar informações de contatos existentes no HubSpot CRM, permitindo manter dados sincronizados e atualizados a partir de conversas no WhatsApp.

Por que este Node existe?

Manter dados de contatos atualizados é crucial para precisão do CRM. O HUBSPOT_CONTACT_UPDATE existe para:

  1. Sincronização de Dados: Atualizar informações quando o contato fornece novos dados
  2. Enriquecimento Progressivo: Adicionar informações conforme são coletadas ao longo do tempo
  3. Correção de Dados: Permitir que contatos corrijam informações incorretas
  4. Atualização de Status: Mudar lifecycle stage, status ou outras propriedades conforme o contato evolui

Como funciona internamente?

Quando o HUBSPOT_CONTACT_UPDATE é executado, o sistema:

  1. Recebe contactId e properties: ID do contato e campos a atualizar
  2. Processa variáveis: Substitui variáveis do contexto pelos valores reais
  3. Monta payload: Cria objeto apenas com propriedades que serão alteradas
  4. Autentica na API: Usa Bearer Token (API Key)
  5. Faz requisição PATCH: Envia atualização para /crm/v3/objects/contacts/{contactId}
  6. Retorna dados atualizados: HubSpot responde com todas as propriedades após update
  7. Armazena resultado: Salva resposta na variável configurada
  8. Em caso de erro: Lança exceção se contato não existir ou houver erro

Código interno (hubspot.executor.ts:70-79): 

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

Quando você DEVE usar este Node?

Use HUBSPOT_CONTACT_UPDATE sempre que precisar de modificar dados existentes de um contato:

Casos de uso

  1. Atualizar telefone/email: Quando contato fornece novos dados de contato
  2. Mudar lifecycle stage: Avançar contato de lead para MQL, SQL ou customer
  3. Adicionar informações: Enriquecer perfil com cargo, empresa, website conforme obtém informações
  4. Atualizar status: Marcar como "Contatado", "Interessado", "Não Responde", etc.
  5. Corrigir dados: Permitir que usuário corrija informações incorretas
  6. Registrar interações: Atualizar última data de contato ou canal de preferência

Quando NÃO usar HUBSPOT_CONTACT_UPDATE

  • Contato não existe: Use HUBSPOT_CONTACT_CREATE para criar novo contato
  • Não tem o ID: Use HUBSPOT_CONTACT_SEARCH para encontrar primeiro
  • Só precisa consultar: Use HUBSPOT_CONTACT_GET para apenas ler dados

Parâmetros Detalhados

contactId (string, obrigatório)

O que é: ID único do contato no HubSpot que será atualizado.

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

Flow completo para testar:

{
  "name": "Teste HubSpot - Atualizar Contato",
  "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 Contato",
        "parameters": {
          "message": "Digite o ID do contato:",
          "variableName": "contact_id"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Novo Telefone",
        "parameters": {
          "message": "Digite o novo telefone:",
          "variableName": "new_phone"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Atualizar Telefone",
        "parameters": {
          "resource": "contacts",
          "operation": "update",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "contactId": "{{contact_id}}",
          "properties": {
            "phone": "{{new_phone}}"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Telefone atualizado com sucesso!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "input_2" },
    { "source": "input_2", "target": "hubspot_1" },
    { "source": "hubspot_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Digite um ID de contato existente e um novo telefone. O sistema atualizará apenas o campo phone.

properties (object, obrigatório)

O que é: Objeto contendo apenas as propriedades que serão atualizadas. Não é necessário enviar todas as propriedades, apenas as que deseja modificar.

Propriedades comuns: - firstname, lastname: Nome - email: Email - phone: Telefone - company: Empresa - jobtitle: Cargo - lifecyclestage: Estágio no funil - hs_lead_status: Status do lead - Qualquer propriedade customizada

config.apiKey (string, obrigatório)

O que é: API Key do HubSpot com permissão de escrita em contatos.

Permissões necessárias: crm.objects.contacts.write

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 "update"
config.apiKey string Sim API Key do HubSpot
contactId string Sim ID do contato a atualizar
properties object Sim Propriedades a atualizar
responseVariable string Não Variável para armazenar resultado

Exemplo 1: Atualizar Dados de Contato

Objetivo: Permitir que usuário atualize suas informações de contato

JSON para Importar

{
  "name": "HubSpot - Atualizar Informações Pessoais",
  "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": "Contact ID",
        "parameters": {
          "variableName": "my_contact_id",
          "value": "12345678901"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Introdução",
        "parameters": {
          "message": "Vamos atualizar suas informações!"
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Novo Nome",
        "parameters": {
          "message": "Qual é o seu nome completo?",
          "variableName": "nome"
        }
      }
    },
    {
      "id": "phone_1",
      "type": "phone",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Novo Telefone",
        "parameters": {
          "message": "Telefone para contato:",
          "variableName": "telefone"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Nova Empresa",
        "parameters": {
          "message": "Nome da empresa:",
          "variableName": "empresa"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Atualizar no HubSpot",
        "parameters": {
          "resource": "contacts",
          "operation": "update",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "contactId": "{{my_contact_id}}",
          "properties": {
            "firstname": "{{nome}}",
            "phone": "{{telefone}}",
            "company": "{{empresa}}"
          }
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1500, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "✅ Suas informações foram atualizadas com sucesso!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "message_1" },
    { "source": "message_1", "target": "input_1" },
    { "source": "input_1", "target": "phone_1" },
    { "source": "phone_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: Vamos atualizar suas informações!
Sistema: Qual é o seu nome completo?
Usuário: João Silva Santos
Sistema: Telefone para contato:
Usuário: 11987654321
Sistema: Nome da empresa:
Usuário: TechCorp Brasil
Sistema: ✅ Suas informações foram atualizadas com sucesso!

Exemplo 2: Avançar Lifecycle Stage

Objetivo: Mudar lifecycle stage do contato baseado em ação

JSON para Importar

{
  "name": "HubSpot - Avançar para Customer",
  "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 Contato",
        "parameters": {
          "message": "Digite o ID do contato que virou cliente:",
          "variableName": "contact_id"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Atualizar para Customer",
        "parameters": {
          "resource": "contacts",
          "operation": "update",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "contactId": "{{contact_id}}",
          "properties": {
            "lifecyclestage": "customer",
            "hs_lead_status": "CONNECTED"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "🎉 Contato atualizado para CUSTOMER com sucesso!"
        }
      }
    },
    {
      "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: Digite o ID do contato que virou cliente:
Usuário: 12345678901
Sistema: 🎉 Contato atualizado para CUSTOMER com sucesso!

Exemplo 3: Enriquecimento Progressivo de Dados

Objetivo: Adicionar informações conforme são coletadas

JSON para Importar

{
  "name": "HubSpot - Enriquecer Perfil",
  "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": "Set Contact ID",
        "parameters": {
          "variableName": "contact_id",
          "value": "12345678901"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Pergunta",
        "parameters": {
          "message": "Notamos que não temos seu cargo registrado. Qual é a sua posição na empresa?"
        }
      }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Cargo",
        "parameters": {
          "message": "Seu cargo:",
          "variableName": "cargo"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Website",
        "parameters": {
          "message": "Qual o website da empresa?",
          "variableName": "website"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Enriquecer Dados",
        "parameters": {
          "resource": "contacts",
          "operation": "update",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "contactId": "{{contact_id}}",
          "properties": {
            "jobtitle": "{{cargo}}",
            "website": "{{website}}"
          }
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Obrigado",
        "parameters": {
          "message": "Obrigado! Seu perfil foi enriquecido."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1500, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "message_1" },
    { "source": "message_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: Notamos que não temos seu cargo registrado. Qual é a sua posição na empresa?
Sistema: Seu cargo:
Usuário: Diretor de TI
Sistema: Qual o website da empresa?
Usuário: www.minhaempresa.com.br
Sistema: Obrigado! Seu perfil foi enriquecido.

Resposta do Node

{
  "id": "12345678901",
  "properties": {
    "email": "joao@empresa.com",
    "firstname": "João Silva Santos",
    "phone": "11987654321",
    "company": "TechCorp Brasil",
    "lastmodifieddate": "2025-01-15T14:20:00.000Z"
  },
  "updatedAt": "2025-01-15T14:20:00.000Z"
}

Boas Práticas

✅ SIM:

  • Envie apenas as propriedades que estão sendo alteradas (não é necessário enviar todas)
  • Use HUBSPOT_CONTACT_GET antes para mostrar dados atuais ao usuário
  • Valide dados antes de atualizar (use nodes de validação como EMAIL, PHONE)
  • Atualize lifecycle stage conforme contato evolui no funil
  • Registre última data de interação em propriedade customizada
  • Use responseVariable nomeada para acessar dados atualizados
  • Implemente confirmação após atualização

❌ NÃO:

  • Atualizar com valores em branco/nulos sem intenção
  • Sobrescrever dados importantes sem confirmação do usuário
  • Fazer updates em loop sem controle
  • Ignorar erros (contato não existe, permissão negada)
  • Atualizar propriedades read-only do sistema
  • Usar update quando deveria criar novo contato

Dicas

💡 Dica 1: Use HUBSPOT_CONTACT_GET → mostrar dados atuais → coletar novos → HUBSPOT_CONTACT_UPDATE para criar experiência de atualização completa.

💡 Dica 2: Crie flows de "correção de dados" onde o usuário pode revisar e atualizar informações desatualizadas.

💡 Dica 3: Implemente atualização automática de última data de contato sempre que usuário interage via WhatsApp.

💡 Dica 4: Use propriedades customizadas para rastrear canal de última interação (WhatsApp, Email, etc.) e atualize automaticamente.

💡 Dica 5: Combine com CONDITION para atualizar apenas se dados realmente mudaram, evitando updates desnecessários.

Próximos Nodes

→ HUBSPOT_CONTACT_GET - Buscar dados atuais antes de atualizar → HUBSPOT_CONTACT_SEARCH - Encontrar contato para atualizar → HUBSPOT_CONTACT_DELETE - Excluir contato → HUBSPOT_DEAL_UPDATE - Atualizar deals associados