Como sincronizar contatos e deals entre Nuvia e HubSpot

A sincronização bidirecional garante que contatos, deals e dados de pipeline estejam sempre atualizados em ambas as plataformas.

Pré-requisito: Integração HubSpot conectada e mapeamentos configurados.

---

Como funciona

A sincronização tem dois gatilhos independentes: por campo (aba Campos) e por etapa do funil (aba Funis). Mapear um campo não move etapa, e mapear uma etapa não sincroniza campo, se você precisa das duas coisas, configure as duas abas. O mapa completo do que vai, do que vem e em quanto tempo está em O que a Nuvia sincroniza com o HubSpot e quando.

Sincronização de contatos

• HubSpot → Nuvia: Contato criado/atualizado no HubSpot → webhook → campos mapeados atualizados na Nuvia.

• Nuvia → HubSpot: Contato criado/atualizado na Nuvia → fila → campos mapeados atualizados no HubSpot.

Como a Nuvia encontra o contato no HubSpot

Ao sincronizar um contato da Nuvia para o HubSpot, a plataforma busca o registro correspondente por e-mail e telefone em uma única consulta. Se o contato tem e-mail preenchido na Nuvia, o match por e-mail tem prioridade sobre o match por telefone, isso aumenta a precisão da vinculação, especialmente quando o formato do telefone difere entre as plataformas. Quando há múltiplos resultados, o registro mais antigo do HubSpot é vinculado.

A busca por telefone cobre o número no formato internacional, com e sem espaço depois do +55. Se o telefone está gravado no HubSpot em outro formato ((11) 99999-9999, 11999999999 sem o código do país, ou com diferença de nono dígito) a busca não encontra o registro e um contato novo é criado.

Por que o mesmo contato virou dois registros no HubSpot

A causa quase sempre é divergência de formato de telefone. Duas ações resolvem a maior parte dos casos:

• Padronizar os telefones no HubSpot no formato internacional (+5511999999999)

• Preencher o e-mail dos contatos na Nuvia, quando existe e-mail, ele tem prioridade na busca e a vinculação fica muito mais precisa

Para o passo a passo de correção, consulte Solução de problemas da integração com HubSpot.

Dados extraídos automaticamente

Sincronização de empresas (enriquecimento)

Quando uma company é criada ou tem propriedades alteradas no HubSpot, a Nuvia recebe o aviso e enriquece a empresa correspondente no seu workspace. Não é preciso configurar nada além da integração conectada.

O que é atualizado

Regras que valem sempre

• A Nuvia nunca cria uma empresa por causa desse aviso. Se nenhuma empresa do seu workspace corresponder ao domínio recebido, nada acontece. Empresas na Nuvia nascem do vínculo real com um lead

• Sem domínio no HubSpot, nada é feito. O domínio é o que permite encontrar a empresa certa

• Sua edição manual vence. Campos que você editou à mão no painel da empresa não são sobrescritos pelo enriquecimento

• Campo vazio não apaga o que existe. Se a propriedade não vier no aviso, o valor atual é preservado

• O domínio principal não muda de identidade. Se a company do HubSpot for reconhecida por um domínio secundário da empresa na Nuvia, os outros campos são enriquecidos, mas o domínio principal permanece o que já estava no registro

• Domínios secundários são limpos antes de gravar. A Nuvia separa a lista, remove repetições e descarta valores que claramente não são domínios

Sincronização do link da conversa

A Nuvia pode enviar automaticamente o link direto de cada conversa para o HubSpot. Com isso, qualquer pessoa no time que acesse o contato no HubSpot consegue abrir a conversa na Nuvia com um clique, sem precisar procurar manualmente.

Como configurar

1. Vá para Integrações > HubSpot > Campos

2. Clique em adicionar mapeamento

3. Na coluna Campo Inteligente (direita), selecione Link da conversa — está no grupo Conversa

4. Na coluna Propriedade do HubSpot (esquerda), escolha a propriedade de contato onde o link será gravado (ex: uma propriedade customizada como nuvia_link)

5. Clique em Salvar mapeamentos

Como funciona

Quando uma conversa é criada na Nuvia, o link direto para ela (no formato https://app.nuvia.ai/messages/conversation/{id}) é enviado automaticamente para o HubSpot no campo mapeado. O envio acontece via fila assíncrona, da mesma forma que os demais campos sincronizados.

Sincronização da data da reunião agendada

Quando o Funil Inteligente agenda uma reunião na agenda do cliente, a Nuvia pode gravar a data e hora dessa reunião em uma propriedade do HubSpot. Assim o time comercial vê o compromisso direto no CRM, sem abrir a conversa.

Como configurar

1. Vá para Integrações > HubSpot > Campos

2. Clique em adicionar mapeamento

3. Na coluna Campo Inteligente (direita), selecione Data agendada, está no grupo Conversa

4. Na coluna Propriedade do HubSpot (esquerda), escolha uma propriedade de data/hora do contato onde o valor será gravado

5. Clique em Salvar mapeamentos

Como funciona

O valor sincronizado é o início da reunião registrada na conversa. Ele viaja no mesmo ciclo de sincronização dos outros campos (como Resumo, Temperatura e Lead Score), não existe gatilho separado nem configuração extra.

Se a reunião for cancelada, a Nuvia envia o campo vazio para o HubSpot, limpando o valor que já havia sido sincronizado. Conversas sem reunião agendada não alteram a propriedade.

Sincronização de deals

A relação entre as etapas do funil da Nuvia e os deal stages do HubSpot é definida na aba Funis. Cada linha do mapeamento tem três colunas: Etapa → Destino (a etapa do funil e o deal stage correspondente), Objetos Sincronizados (os interruptores Contato, Deal e Lead) e Direção.

Direção da sincronização (por etapa)

A direção é definida por etapa, na coluna Direção do mapeamento:

Avançado: a mesma etapa em dois funis do mesmo objeto

Uma etapa da Nuvia pode ser mapeada para mais de um funil do mesmo objeto no HubSpot. O caso mais comum é o contato, que no HubSpot tem dois funis independentes:

• Lifecycle Stage (lifecyclestage) → o estágio de ciclo de vida do contato

• Lead Status (hs_lead_status) → o status de lead do contato

Você pode mapear a mesma etapa da Nuvia para os dois ao mesmo tempo: basta adicionar duas linhas de mapeamento para aquela etapa com o objeto Contato, cada uma apontando para um funil diferente. Quando a conversa chega nessa etapa, a Nuvia atualiza todas as propriedades mapeadas, no exemplo, lifecyclestage e hs_lead_status.

Quando o deal não é movido

Antes de mover um deal, a Nuvia verifica a situação atual dele no HubSpot e não escreve em dois casos:

• Deal já fechado (ganho ou perdido) no HubSpot, não é movido

• Etapa anterior à atual, o deal não anda para trás

Nos dois casos o deal permanece como está e o evento fica registrado no Histórico, sem erro. Essas travas valem apenas para deals: etapas de contato (Lifecycle Stage e Lead Status) e de lead são gravadas direto, mesmo que representem um retrocesso.

A verificação depende de a Nuvia conseguir ler o funil no HubSpot. Se a leitura falhar, ou se a etapa atual do deal não for encontrada no funil, a Nuvia grava assim mesmo, a trava não bloqueia por precaução.

Quantos deals um contato pode ter

O deal é vinculado à conversa, mas a Nuvia não cria um deal novo às cegas: antes de criar, ela procura no HubSpot um deal já associado àquele contato no mesmo funil e reaproveita esse registro. Duas conversas do mesmo contato mapeadas para o mesmo funil, portanto, compartilham o mesmo deal.

Dois deals surgem quando as conversas estão mapeadas para funis diferentes do HubSpot, quando o contato ainda não estava vinculado a um registro do HubSpot no momento da criação, ou quando a consulta dos deals associados falha.

Criar Leads no HubSpot por etapa

Além de contato e deal, a Nuvia pode criar Leads no HubSpot automaticamente conforme a conversa avança pelas etapas do funil. No mapeamento de etapas (Integrações > HubSpot), cada etapa tem os interruptores Contato, Deal e Lead.

• Lead (por etapa) → quando a conversa chega nessa etapa, a Nuvia cria um Lead no HubSpot. É um upsert: se o contato já tem um Lead, ele é vinculado/atualizado em vez de duplicar.

• Rótulo do lead → o campo aparece quando o interruptor Lead está ligado. Define o “estágio” do lead naquela etapa (ex.: WARM). No HubSpot, Leads não têm pipeline — o estágio é justamente esse rótulo (hs_lead_label). Desligar o interruptor descarta o rótulo ao salvar (não fica rótulo fantasma).

• Template do nome do lead → abaixo do template de nome do deal, define como o Lead é nomeado no HubSpot, com o mesmo autocomplete de variáveis dos templates.

Gatilhos, owner e visualização do Lead

• Campanhas: os eventos de gatilho incluem Lead criado e Lead atualizado, além dos eventos de contato/deal.

• Owner: na sincronização de owner (Integrações > HubSpot > Usuários), a Fonte de sincronização aceita também Lead Owner, além de Contact Owner e Deal Owner.

• Painel do contato: no accordion do HubSpot (drawer do contato), aparece o bloco ID do Lead, com link para o registro no HubSpot e botão de copiar.

Sincronização de owner (atendente)

Quando o Contact Owner ou Deal Owner é alterado no HubSpot, a Nuvia pode atualizar automaticamente o atendente vinculado à conversa aberta do contato. Útil para manter rastreabilidade quando o vendedor responsável muda de mãos no CRM.

Como ativar:

1. Em Integrações > HubSpot > Usuários, configure a Fonte de sincronização (Contact Owner, Deal Owner ou Lead Owner) e mapeie os usuários do HubSpot para os usuários da Nuvia

2. Em Integrações > HubSpot > Avançado, ative o toggle Atualizar o owner quando o Contact/Deal for atualizado no HubSpot

Comportamento:

Monitorar histórico

1. Vá para Integrações > HubSpot > Histórico

2. Filtre por objeto, direção, status e período

3. Clique em qualquer registro para abrir o painel de detalhes da sincronização

Tipos de evento no histórico

O histórico mostra um rótulo amigável para cada evento (em vez do nome técnico) e você pode filtrar por ele. Entre os eventos de mudança de etapa por objeto:

Status de uma sincronização

Ver o motivo de uma falha

Ao abrir um registro com status Parcial ou Falha, o painel de detalhes mostra:

• Resumo da operação (o que foi sincronizado)

• Erro → a mensagem real devolvida pelo HubSpot. Quando uma propriedade é reprovada na validação do HubSpot, você vê a causa exata: qual objeto (contato ou deal) e qual propriedade falhou

• Detalhes técnicos → o corpo completo do erro do HubSpot, útil para ajustar o mapeamento de campos

Por que um contato não entrou em uma campanha

Quando um evento do HubSpot deveria disparar uma campanha e o contato não é inscrito, o histórico registra o motivo do descarte. Abra o registro correspondente e veja a razão. As mais comuns são:

Desvincular contato do HubSpot

Você pode remover o vínculo entre um contato na Nuvia e o registro correspondente no HubSpot. Após a desvinculação, alterações no HubSpot não atualizam mais esse contato na Nuvia (e vice-versa) até que um novo vínculo seja criado.

Passo a passo

1. Vá para Listas e Objetos > Contatos

2. Na listagem, localize o contato vinculado ao HubSpot

3. Clique no menu de três pontos na linha do contato

4. Clique em Desvincular HubSpot

5. Um modal de confirmação aparece: “Desvincular contato do HubSpot? O ID do HubSpot será removido deste contato. Você precisará religar manualmente para sincronizar novamente.”

6. Clique em Desvincular para confirmar

O que acontece

• Os campos de vínculo com o HubSpot (ID externo, tipo de CRM e data da última sincronização) são removidos do contato

• A sincronização bidirecional para esse contato é interrompida

• O contato continua existindo na Nuvia com todos os dados, apenas o link com o HubSpot é cortado

• Para religar, será necessário um novo mapeamento manual ou reimportação

Importar listas do HubSpot

1. Na integração HubSpot, acesse Listas

2. Busque a lista desejada

3. Clique em Importar membros