Nó HubSpot

O nó de workflow HubSpot chama a HubSpot CRM API v3 para gerenciar contatos, empresas e deals. Use-o para sincronizar leads do WhatsApp no HubSpot ou ler dados de CRM dentro das suas automações.

ID do nó no editor: hubspot_request
Base URL: https://api.hubapi.com/crm/v3/objects/
Auth: Authorization: Bearer {{hubspot_api_key}}

O que faz

• Envia requisições HTTP autenticadas para endpoints do HubSpot CRM
• Suporta GET, POST, PUT, PATCH e DELETE
• Retorna status HTTP, data de resposta e headers de resposta
• Inclui templates de operação para ações comuns de CRM (listar/criar/atualizar contatos, listar empresas e deals)

Pré-requisitos

1. Uma conta HubSpot (Free, Starter, Professional ou Enterprise)
2. Um Private App access token ou token OAuth com escopos de CRM
3. Chave de integração hubspot_api_key em Configurações → Chaves de API

Criando um token de Private App

1. No HubSpot, acesse Settings → Integrations → Private Apps
2. Crie um novo private app com escopos como crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.deals.read, crm.objects.deals.write
3. Copie o access token
4. No WhatsWave, adicione a chave de integração hubspot_api_key com esse valor de token

Como configurar

Passo 1 — Definir credenciais

1. Abra Configurações → Chaves de API
2. Em Chaves de integração, adicione:
   • Nome: hubspot_api_key
   • Valor: seu HubSpot Private App access token

O template de header padrão envia Authorization: Bearer {{hubspot_api_key}}.

Passo 2 — Adicionar o nó

1. Abra Automações e edite seu workflow
2. Na paleta, abra a categoria Marketing
3. Arraste HubSpot para o canvas
4. Conecte-o após o gatilho ou nós de preparação de dados

Passo 3 — Escolher um template de operação ou configurar manualmente

Passo 4 — Configurar campos da requisição

Exemplo — criar contato a partir de lead WhatsApp (POST):

• URL: https://api.hubapi.com/crm/v3/objects/contacts
• Method: POST
• Body:

{
  "properties": {
    "email": "{{contact.email}}",
    "firstname": "{{contact.name}}",
    "phone": "{{contact.phone}}",
    "hs_lead_status": "NEW"
  }
}

Exemplo — atualizar contato (PATCH):

• URL: https://api.hubapi.com/crm/v3/objects/contacts/{{variables.hubspot_contact_id}}
• Method: PATCH
• Body:

{
  "properties": {
    "notes_last_contacted": "{{date:now}}",
    "lifecyclestage": "opportunity"
  }
}

Todos os campos suportam variáveis de workflow.

Passo 5 — Usar dados da resposta

O HubSpot retorna dados do objeto criado/atualizado em data. Referencie em nós posteriores:

Contact ID: {{hubspot_1.data.id}}
Email: {{hubspot_1.data.properties.email}}

Armazene o contact ID em um nó Variable para passos de atualização posteriores no fluxo.

Saídas do nó

Dicas e boas práticas

• E-mail é o identificador principal — o HubSpot deduplica contatos por e-mail; sempre inclua email ao criar contatos
• Use PATCH (não PUT) para atualizações parciais de propriedades em registros existentes
• Armazene IDs de contato/deal do HubSpot em contatos WhatsWave como campos customizados para sync bidirecional
• Configure webhooks do HubSpot para mudanças de estágio de deal e aponte-os para um workflow Webhook do WhatsWave
• Para busca por e-mail, use a Search API (POST /crm/v3/objects/contacts/search) via configuração customizada de URL
• Paginate chamadas de listagem com ?limit=100&after={{cursor}} usando o valor paging.next.after de respostas anteriores
• Teste com um sandbox HubSpot ou portal de desenvolvimento quando disponível

Exemplos de casos de uso

Novo contato WhatsApp → lead HubSpot

1. Gatilho — novo contato criado no WhatsWave
2. HubSpot POST — criar contato com telefone e nome
3. Variable — salvar {{hubspot_1.data.id}} como hubspot_contact_id
4. Enviar mensagem — resposta de boas-vindas no WhatsApp

Agente qualifica lead → atualizar lifecycle stage

1. AI Agent define variables.lifecycle_stage como opportunity
2. HubSpot PATCH — atualizar lifecycle stage do contato
3. HubSpot POST — criar deal vinculado ao contato (URL/body customizados)

Deal ganho no HubSpot → agradecimento WhatsApp

1. Gatilho Webhook — HubSpot deal.propertyChange (stage = closedwon)
2. HubSpot GET — buscar deal e contato associado
3. Enviar mensagem — agradecimento e instruções de onboarding

FAQ

Por que o nó retorna 401 Unauthorized?
O access token está ausente, expirado ou sem os escopos de CRM necessários. Verifique hubspot_api_key em Configurações → Chaves de API e confira os escopos do Private App.

Por que 409 Conflict ao criar contato?
Já existe um contato com esse e-mail. Use PATCH para atualizar, ou a Search API para encontrar o ID existente primeiro.

Posso criar propriedades customizadas?
Sim — inclua qualquer nome interno válido de propriedade HubSpot no objeto properties. Crie propriedades customizadas nas Configurações do HubSpot primeiro.

Qual a diferença entre este nó e o nó HTTP?
Este nó pré-configura base URLs do HubSpot, header de auth e templates de operação CRM comuns. Use HTTP apenas para endpoints HubSpot não suportados (Marketing Email, Tickets, etc.).

Como associo um deal a um contato?
Após criar ambos os registros, chame PUT /crm/v3/objects/deals/{dealId}/associations/contacts/{contactId}/deal_to_contact via configuração customizada de URL.

Referência da API

Relacionados

• Visão geral de Marketing
• Variáveis no workflow
• Webhooks recebidos
• Nó HTTP