# Integração HubSpot: o agente da Nodale sincroniza leads

Bastien Izzo, CEO · Publicado em 4 de novembro de 2026
<https://nodale.ai/pt/integracoes/hubspot>

> **Em resumo.** Ligue o HubSpot a partir da página de integrações do seu espaço de trabalho Nodale. Depois de cada conversa, a Nodale encontra ou cria o contacto e a sua empresa, preenche as propriedades do HubSpot que mapeou na direção de sincronização escolhida e acrescenta uma nota ao contacto, à sua empresa e aos seus negócios abertos.

A Nodale é um agente de IA que transforma o inbound em leads quentes: os visitantes de sites B2B obtêm respostas e uma demo ao vivo, 24/7 e em mais de 50 línguas, e indicam a sua intenção, o seu caso de uso e o seu orçamento, para que as empresas convertam uma parte maior do tráfego pelo qual já pagam.

Esta página destina-se ao administrador de um espaço de trabalho Nodale que liga o HubSpot. Explica o que a Nodale pede ao HubSpot, o que lá escreve e o que lê de volta.

## Instalar a integração

Tem de ser **administrador do seu espaço de trabalho Nodale** e um utilizador do HubSpot com permissão para instalar aplicações no seu portal. Os outros membros do espaço de trabalho veem a ligação, mas não a podem alterar.

1. Na Nodale, abra **Settings**, depois **Workspace**, depois **Integrations**, e escolha o cartão **HubSpot**.
2. Clique em **Connect HubSpot**. O HubSpot abre a sua página de consentimento.
3. Escolha o portal a ligar, leia os scopes (listados abaixo) e aceite-os.
4. O HubSpot reencaminha-o para a Nodale, que mostra: «HubSpot is connected. Your portal is shown below.»

<!-- screenshot: hubspot/01-card.png, hubspot/02-connect.png, hubspot/03-consent.png, hubspot/04-connected.png -->

O cartão da ligação mostra então o portal, quando foi ligado e a última sincronização. Um espaço de trabalho Nodale liga um único portal HubSpot.

Ao ligar-se, a Nodale acrescenta ao seu portal uma propriedade de empresa oculta, **Nodale record ID** (`nodale_external_id`), num grupo de propriedades chamado **Nodale**. Permite à Nodale encontrar as empresas que criou.

## Os scopes que a Nodale pede

O HubSpot mostra estes scopes na sua página de consentimento. Todos são obrigatórios.

| Scope | O que a Nodale faz com ele |
|---|---|
| `oauth` | Identifica o portal que ligou. |
| `crm.objects.contacts.read` | Encontra um contacto pelo email e lê as propriedades que mapeou. |
| `crm.objects.contacts.write` | Cria e atualiza contactos, e associa um contacto à sua empresa. |
| `crm.objects.companies.read` | Encontra uma empresa pelo domínio ou pela sua associação ao contacto, e lê as suas propriedades mapeadas. |
| `crm.objects.companies.write` | Cria e atualiza empresas. |
| `crm.objects.deals.read` | Lista os seus pipelines de negócios e encontra os negócios abertos do contacto, para lhes associar a nota. |
| `crm.objects.deals.write` | Pedido juntamente com os scopes do CRM. A Nodale não cria nem altera nenhum negócio. |
| `crm.schemas.contacts.read` | Lista as propriedades de contacto que pode mapear. |
| `crm.schemas.contacts.write` | Cria uma propriedade de contacto quando a pede a partir da Nodale. |
| `crm.schemas.companies.read` | Lista as propriedades de empresa que pode mapear. |
| `crm.schemas.companies.write` | Cria uma propriedade de empresa quando a pede, e a propriedade Nodale record ID. |
| `crm.schemas.deals.read` | Pedido juntamente com os scopes do CRM. A Nodale não mapeia nenhuma propriedade de negócio. |
| `crm.schemas.deals.write` | Pedido juntamente com os scopes do CRM. A Nodale não cria nenhuma propriedade de negócio. |
| `scheduler.meetings.meeting-link.read` | Lê as suas ligações de reuniões do HubSpot, para que o agente marque reuniões nelas (ver abaixo). |

## Contactos e empresas

### Quando a Nodale lê e escreve no HubSpot

- **Assim que o visitante indica um email**, a Nodale lê o contacto e a sua empresa no HubSpot, para que o agente saiba o que o seu CRM já sabe sobre ele. Ler nunca escreve nada no HubSpot.
- **Depois de cada conversa**, quando a Nodale termina o seu resumo, envia o lead para o HubSpot. Um lead é enviado quando tem um email, esteja qualificado ou não.
- Os leads anteriores à ligação não são enviados.

### Como a Nodale encontra o contacto e a empresa

- **O contacto**: o que a Nodale já associou; senão, o que tem o mesmo **email**; senão, a Nodale cria-o. Um contacto arquivado não é tocado.
- **A empresa**: a empresa principal do contacto no HubSpot; senão, a que a Nodale já associou; senão, a empresa com o mesmo **domínio**; senão, a Nodale cria-a com esse domínio e associa-lhe o contacto. Não se procura nenhuma empresa para um endereço de email pessoal (Gmail, por exemplo).

### Mapear os campos

Abra o separador **Mapping** da página do HubSpot. Cada linha envia um campo da Nodale para uma propriedade do HubSpot.

![O separador Mapping da integração HubSpot na Nodale](https://nodale.ai/assets/integrations/hubspot/mapping.webp)

- **Always sent here**: o email vai para o `email` do contacto, o domínio da empresa para o `domain` da empresa. Preenchem a propriedade quando está vazia.
- **Identity**: nome próprio, apelido, cargo.
- **Context**: fonte UTM, meio UTM, campanha UTM e site de referência, da primeira visita do lead.
- **Qualification**: os elementos do modelo de qualificação do seu agente.
- **Custom**: os campos personalizados do seu espaço de trabalho, no contacto ou na empresa.

Da primeira vez, a Nodale propõe um mapeamento: os campos de identidade e de contexto associados às propriedades do HubSpot com o mesmo nome. Valide-o, ou comece em branco.

As alterações ficam em rascunho até clicar em **Validate**. Remover um mapeamento não apaga nenhum campo da Nodale nem nenhuma propriedade do HubSpot. Um campo com erro não é enviado até o corrigir; tudo o resto continua a sincronizar.

**Criar uma propriedade do HubSpot.** Para um campo sem propriedade, escolha **Create a HubSpot property**: ao validar, a Nodale acrescenta-a ao HubSpot no grupo **Nodale** (com o nome `nodale_...`) e envia o campo para lá.

**Importar propriedades do HubSpot.** **Add HubSpot properties to Nodale** transforma as propriedades do HubSpot que assinalar em campos da Nodale, mapeados para elas. Uma lista pendente torna-se um campo de escolha, uma caixa de verificação um campo sim/não, e tudo o resto texto.

**Fazer corresponder os valores.** Um campo de escolha enviado para uma lista pendente precisa que cada um dos seus valores corresponda a uma opção do HubSpot. Não é enviado enquanto todos os valores não tiverem a sua.

### Escolher a direção de sincronização

Cada campo mapeado tem uma direção de sincronização. A predefinida é **Bi-sync on create, HubSpot priority on update**. Um valor vazio na Nodale nunca apaga o HubSpot.

![O menu da direção de sincronização de um campo mapeado na Nodale](https://nodale.ai/assets/integrations/hubspot/sync-direction.webp)

| Direção de sincronização | Primeiro envio do lead | Envios seguintes | Ambos têm um valor |
|---|---|---|---|
| **Bi-sync** | Cada lado preenche o valor vazio do outro; um valor do HubSpot já preenchido ganha | Propaga-se o lado alterado desde a última sincronização | Primeiro envio: ganha o HubSpot. Depois, o lado alterado desde a última sincronização; o HubSpot se ambos mudaram |
| **Bi-sync on create, HubSpot priority on update** (predefinida) | Cada lado preenche o valor vazio do outro | Ganha o HubSpot se tiver um valor; senão, a Nodale preenche-o | Cada um mantém o seu no primeiro envio, depois ganha o HubSpot |
| **HubSpot priority** | O valor do HubSpot volta para a Nodale; a Nodale nunca escreve | Igual | Ganha o HubSpot |
| **Nodale priority** | A Nodale escreve, mesmo por cima de um valor | Igual; nada volta | Ganha a Nodale |
| **Deactivate sync** | Nada circula | Nada circula | Cada um mantém o seu |

Por exemplo, o HubSpot tem «Marketing Manager» como cargo e o visitante diz ao agente «Head of Growth». Com a predefinição, o HubSpot mantém «Marketing Manager». Com Nodale priority, o HubSpot recebe «Head of Growth».

O HubSpot devolve valores à Nodale apenas para o nome próprio, o apelido, o cargo e os campos de qualificação. Uma propriedade do HubSpot só de leitura só pode estar em HubSpot priority ou desativada.

## A nota de cada conversa

Cada conversa torna-se **uma nota** no HubSpot, associada ao contacto, à sua empresa e aos negócios abertos do contacto. É escrita uma vez e nunca atualizada. A sua data é o início da conversa.

<!-- screenshot: hubspot/06-note-tab.png, hubspot/07-note-in-hubspot.png -->

Escolha o que contém no separador **Note**. Por esta ordem:

| Bloco | O que contém | Pode ser desativado |
|---|---|---|
| Summary | Ao que veio o visitante e como correu a conversa. | Não |
| Next step | O que o agente recomenda fazer a seguir. | Sim |
| Qualification criteria | Os valores recolhidos face aos seus critérios. | Sim |
| Qualification framework | Uma linha curta por pilar do seu modelo (MEDDIC por predefinição; SPICED, BANT, CHAMP ou NEAT), escrita a partir da conversa. Não é mostrado quando qualifica com a sua própria lista. | Sim |
| Demos shown | As demos reproduzidas. | Sim |
| Pages visited | As páginas vistas antes e durante a conversa. | Sim |
| Open the lead in Nodale | Uma ligação para o lead. | Não |
| Full transcript | A conversa completa, com linhas que começam por «Visitor:» ou «Agent:». | Sim |

Todos os blocos estão ativos por predefinição. Uma nota fica abaixo do limite de tamanho do HubSpot: primeiro a transcrição é encurtada («Transcript shortened, the full conversation is in Nodale.»), depois os últimos blocos são omitidos. O resumo e a ligação ficam sempre. Quando o conteúdo de uma conversa deixa de ser guardado, a sua nota segue sem a transcrição.

## Negócios

A Nodale **não cria nenhum negócio nem altera nenhum**: nem montante, nem fase, nem propriedade de negócio.

Associa a nota de cada conversa aos **negócios abertos** do contacto: os negócios do contacto no seu pipeline predefinido (ou, se não tiver nenhuma fase aberta, o primeiro pipeline que tenha uma) cuja fase não está fechada. Um contacto que a Nodale acabou de criar ainda não tem nenhum negócio, por isso a sua primeira nota vai apenas para o contacto e para a empresa.

## Marcar reuniões com o HubSpot Meetings

O agente pode marcar reuniões nas suas ligações de reuniões do HubSpot, durante a conversa. Usa a mesma ligação ao HubSpot: não há mais nada a instalar. Um portal ligado antes desta funcionalidade mostra **To reconnect** nos seus outcomes de marcação: volte a ligar o HubSpot uma vez para conceder o scope das ligações de reuniões.

1. Na Nodale, abra **Agents**, depois o separador **Outcomes**, e crie um **New outcome** do tipo **Meeting booking**.
2. Escolha um **Meeting type**. Cada ligação de reuniões do HubSpot, pessoal ou de equipa, figura uma vez por duração, por exemplo «HubSpot Meetings · Intro call · 30 min».
3. Associe cada **pergunta obrigatória** da ligação de reuniões a um elemento que o agente recolhe. O nome e o email são preenchidos automaticamente. Uma pergunta de telefone não é suportada: torne-a opcional no HubSpot.

Quando o visitante indicou um email profissional e o momento é oportuno, o agente propõe-lhe horários no seu fuso horário e na sua língua, e marca o que ele escolher. O HubSpot cria a reunião com o nome, o email, o fuso horário e as respostas do visitante, segundo as regras da própria ligação (horário, antecedência, quem da equipa está disponível). Se o horário entretanto tiver sido ocupado, o agente propõe outros.

![Os horários que o agente propõe ao visitante na conversa](https://nodale.ai/assets/integrations/hubspot/booking.webp)

A Nodale não cancela nem reagenda reuniões: isso faz-se no HubSpot.

## Dados e desligação

- A Nodale escreve apenas as propriedades que mapeou, a nota e a propriedade de empresa Nodale record ID.
- Desligar não apaga nada no HubSpot. Apagar um lead na Nodale também não apaga nada no HubSpot.
- Dúvidas: support@nodale.ai.

## Resolução de problemas

| Mensagem na Nodale | O que aconteceu |
|---|---|
| HubSpot was not connected: access was refused on the HubSpot page. | A página de consentimento foi fechada ou recusada. |
| The HubSpot connection link expired or was already used. Start again from this page. | A ligação é válida durante dez minutos, uma única vez. Clique novamente em Connect HubSpot. |
| HubSpot did not answer. Please try again in a few minutes. | O HubSpot estava indisponível. |
| HubSpot refused the connection. Please try again, or contact support if it keeps happening. | O HubSpot rejeitou o pedido. |
| Couldn't connect HubSpot. Please try again. | Qualquer outra falha. |