1. [Ajuda](https://nuvia.ai/docs) 2. [Integrações](https://nuvia.ai/docs/colecoes/19378002-integracoes) 3. [Hubspot](https://nuvia.ai/docs/colecoes/19431232-hubspot) # Como configurar integração com HubSpot Sincronize o HubSpot com a Nuvia: contatos, empresas e deals em tempo real, com mapeamento de campos, etapas do funil e regras bidirecionais configuráveis. Disponível em Plataforma > Integrações > HubSpot Quem pode fazer Administrador Atualizado em 3 de novembro de 2026 [Hubspot](https://nuvia.ai/docs/colecoes/19431232-hubspot) 1. [Como configurar integração com HubSpot](https://nuvia.ai/docs/artigos/14501908-como-configurar-integracao-com-hubspot) 2. [Como sincronizar contatos e deals entre Nuvia e HubSpot](https://nuvia.ai/docs/artigos/14590403-como-sincronizar-contatos-e-deals-entre-nuvia-e-hubspot) 3. [O que a Nuvia sincroniza com o HubSpot e quando](https://nuvia.ai/docs/artigos/16473526-o-que-a-nuvia-sincroniza-com-o-hubspot-e-quando) 4. [Como mapear campos entre a Nuvia e o HubSpot](https://nuvia.ai/docs/artigos/16474177-como-mapear-campos-entre-a-nuvia-e-o-hubspot) 5. [Solução de problemas da integração com HubSpot](https://nuvia.ai/docs/artigos/16474434-solucao-de-problemas-da-integracao-com-hubspot) 6. [Como disparar templates WhatsApp na Nuvia direto de um workflow do HubSpot](https://nuvia.ai/docs/artigos/15879535-como-disparar-templates-whatsapp-na-nuvia-direto-de-um-workflow-do-hubspot) 7. [Como inscrever leads/contatos em campanhas da Nuvia direto de um workflow do Hubspot](https://nuvia.ai/docs/artigos/15879734-como-inscrever-leads-contatos-em-campanhas-da-nuvia-direto-de-um-workflow-do-hubspot) A integração com HubSpot sincroniza automaticamente contatos e empresas entre a Nuvia e sua conta de HubSpot. Isso garante que seus dados permaneçam sempre atualizados em ambas as plataformas, eliminando a necessidade de sincronização manual e criando um ciclo de feedback contínuo entre inbound e outbound. ## O que você precisa antes de começar - Acesso de **Proprietário** ou **Administrador** na sua conta Nuvia - Conta ativa no **HubSpot** (qualquer plano) - Permissões para conectar aplicações de terceiros na sua conta HubSpot - Clareza sobre quais campos deseja sincronizar entre as plataformas - Definição do seu código de DDI (codigo que identifica o Pais) padrão ### Conectar sua conta do HubSpot 1. Vá para **Configurações** > **Integrações** 2. Localize **HubSpot** na lista e clique para abrir o painel 3. Clique em **Integrar ** e em seguida **Adicionar conta** 4. Faça login no HubSpot e conceda as permissões solicitadas 5. Você será redirecionado de volta à Nuvia com o status **Conectado** Importante a conexão requer permissões de propriedade ou administração na sua conta HubSpot. Importante conectar a conta **não** importa a base que já existe no HubSpot. A partir da conexão, a Nuvia sincroniza apenas o que muda daqui para frente. Para trazer contatos que já existem no HubSpot, use **Listas > Importar membros**. ### Configurar o mapeamento de campos O mapeamento de campos determina quais informações serão sincronizadas entre Nuvia e HubSpot. A Nuvia não vem com mapeamentos pré-configurados, todos são definidos manualmente. 1. Na página de integração HubSpot, localize sua conta e clique em **Configurar** 2. Clique em **Campos** 3. Clique em **adicionar mapeamento** 4. Selecione o campo da Nuvia (direita) e a propriedade do HubSpot (esquerda) para associação 5. Clique em **Salvar mapeamentos** Dica campos customizados são totalmente suportados. Qualquer propriedade do HubSpot (incluindo propriedades customizadas) pode ser mapeada para qualquer campo personalizado da Nuvia. Crítico campos de **lista suspensa** e **múltipla escolha** exigem que o texto da opção na Nuvia seja idêntico ao do HubSpot — inclusive maiúsculas, acentos e espaços. Qualquer divergência faz o HubSpot recusar **o registro inteiro**, e todos os outros campos daquele contato deixam de ser gravados, sem aviso na tela. Antes de mapear campos de seleção, leia [Como mapear campos entre a Nuvia e o HubSpot](https://nuvia.ai/docs/artigos/16474177-como-mapear-campos-entre-a-nuvia-e-o-hubspot). ### Configurar o mapeamento de etapas do funil Alinha os estágios de vendas entre as plataformas para que movimentações no pipeline sejam refletidas automaticamente. 1. Na página de integração HubSpot, clique na aba **Funis** 2. Defina o template usado para nomear os deals criados automaticamente no HubSpot. 3. Para cada etapa do funil Nuvia, selecione o deal stage correspondente no HubSpot 4. Clique em **Salvar mapeamento** Nota mapeamento de campos e mapeamento de etapas são mecanismos independentes. Mapear um campo não move etapa, e mapear uma etapa não sincroniza campo. Detalhes em [O que a Nuvia sincroniza com o HubSpot e quando](https://nuvia.ai/docs/artigos/16473526-o-que-a-nuvia-sincroniza-com-o-hubspot-e-quando). ### Configurar o DDI padrão O DDI padrão completa o código de país dos telefones que **chegam do HubSpot** sem essa informação, para que o contato seja criado corretamente na Nuvia. 1. Abra a aba **Avançado** 2. Em **Configurações de Telefone**, selecione o DDI no seletor (ex.: +55 - Brasil) A configuração é salva automaticamente ao selecionar — não existe botão **Salvar**. Como a regra funciona: - Só é aplicada quando o número tem **11 dígitos ou menos** e ainda não começa com aquele DDI - Números que já chegam no formato internacional (com +) não são alterados - Para o Brasil, um número de 8 dígitos começando com 6, 7, 8 ou 9 recebe o nono dígito automaticamente - Números com menos de 8 dígitos são descartados e o contato não é criado - A opção **Nenhum (detectar automaticamente)** faz a Nuvia tentar identificar o país pelos primeiros dígitos, o que pode errar Importante o DDI padrão atua **apenas na entrada**. Ele **não altera** o telefone que a Nuvia envia ao HubSpot — na saída vai o DDI e o número exatamente como estão gravados no contato da Nuvia. Se os telefones chegam errados ao HubSpot, a correção é no cadastro do contato, não nesta configuração. ### Configurações da aba Avançado Além do DDI padrão, a aba **Avançado** concentra as regras de sincronização da conta. ConfiguraçãoO que faz **Atualizar campos** O botão **Sincronizar campos** recarrega as propriedades do HubSpot, libera as novas para mapeamento e remove os mapeamentos de propriedades que não existem mais **Criação automática de contatos** Cria ou vincula o contato no HubSpot ao iniciar uma conversa **Atualizar o owner quando o Contact/Deal for atualizado no HubSpot** Reflete na Nuvia a troca de responsável feita no HubSpot **Consultar propriedades antes do agente** Busca as propriedades do contato no HubSpot em tempo real antes de cada resposta do agente. Adiciona uma consulta por atendimento (custo e limite de API) e vem desligado por padrão **Enviar transcrição para o HubSpot após ser resolvida** Envia o conteúdo da conversa resolvida como registro de comunicação associado ao contato. Vale para WhatsApp e LinkedIn **Fontes de eventos do webhook** Permite descartar eventos vindos de determinadas origens do HubSpot (edição manual, formulário, automação, workflow, integrações e API, importação, migração) Importante desligue uma **fonte de eventos** apenas em situação de emergência. Os eventos daquela origem passam a ser descartados na entrada e não são recuperados depois. ### Criação automática de contatos Na aba **Avançado**, localize **Criação automática de contatos ** e clique no botão para ativar. Quando ativado, todo contato que iniciar uma conversa é criado no HubSpot – ou vinculado, se já existir um registro com o mesmo telefone ou e-mail. - **Ativado:** garante que nenhuma conversa fique sem contato correspondente no HubSpot - **Desativado:** o controle passa a ser individual por etapa do funil (apenas as etapas configuradas para criar contato no HubSpot irão disparar a criação) Dica esta configuração tem prioridade sobre o controle por etapa do funil. Se estiver ativada, cria o contato em qualquer nova conversa, independente da etapa. ### Atualizar o owner quando o Contact/Deal for atualizado no HubSpot Toggle na aba **Avançado**. Quando ativado, mudanças no **Contact Owner** ou **Deal Owner** feitas no HubSpot são refletidas automaticamente no atendente vinculado à conversa aberta do contato na Nuvia – mantendo o mesmo agente ou IA respondendo, sem transferir o atendimento. #### **Como configurar:** 1. Na aba **Usuários**, configure a **Fonte de sincronização** (Contact Owner ou Deal Owner) e mapeie os usuários do HubSpot para os usuários da Nuvia 2. Na aba **Avançado**, ative o toggle **Atualizar o owner quando o Contact/Deal for atualizado no HubSpot** #### **Comportamento:** - A Nuvia recebe o webhook do HubSpot com o novo owner - Identifica o usuário Nuvia correspondente usando o mapeamento da aba **Usuários** - Localiza a última conversa aberta do contato e atualiza o atendente vinculado - O agente ou humano que estava respondendo continua respondendo (a conversa não é transferida) Importante o toggle fica desabilitado enquanto a **Fonte de sincronização** estiver como **Desativado**. Configure os mapeamentos de usuários na aba **Usuários** antes de ativar. Dica se o novo owner do HubSpot não tiver mapeamento para um usuário Nuvia, ou se o contato não tiver conversa aberta no momento do webhook, a Nuvia ignora o evento silenciosamente e não altera nada. ### Consultar o histórico de sincronização O histórico de sincronização mostra um registro completo de todas as sincronizações, atualizações, erros e conflitos. 1. Na página de integração HubSpot, clique na aba **Histórico** 2. Revise os registros por data/hora, tipo, ação e status 3. Clique em um erro para ver detalhes e orientações de resolução Dica os logs são mantidos por **7 dias** e não existe alerta automático de falha. Consulte o Histórico com regularidade, principalmente depois de mexer em campos ou etapas. Para o passo a passo de diagnóstico, veja [Solução de problemas da integração com HubSpot](https://nuvia.ai/docs/artigos/16474434-solucao-de-problemas-da-integracao-com-hubspot). #### Dois novos tipos de evento no filtro O filtro de tipo de evento do histórico ganhou duas opções: - **Proprietário atribuído** → a Nuvia definiu o proprietário (owner) do contato ou do deal no HubSpot. Quando a atribuição falha, o evento aparece como **Falha na atribuição de proprietário** - **Transcrição enviada** → a Nuvia enviou a transcrição da conversa para o HubSpot. Quando o envio falha, o evento aparece como **Falha no envio da transcrição** #### Ver os dados por trás de cada evento Ao clicar em um evento do histórico, o painel de detalhe abre com até três blocos de dados, quais aparecem depende da direção do evento. - **Campos mapeados** (nos dois sentidos) → só os campos que você mapeou em **Campos**, com o valor que viajou naquele evento. Campo que não foi enviado aparece marcado com **(não enviado)** - **Campos recebidos do HubSpot** (só quando o evento veio do HubSpot) → tudo que o HubSpot devolveu naquele evento, e não apenas o que você mapeou, incluindo campos nativos como e-mail, telefone e empresa. Cada linha traz o nome amigável da propriedade, o nome técnico embaixo (ex.: contacts.email) e a marca **(mapeado)** quando aquela propriedade está no seu mapeamento - **Dados da Nuvia no envio** (só quando o evento saiu da Nuvia) → o estado do registro na Nuvia no instante do envio. É o bloco que explica por que um campo saiu vazio ou com valor diferente do esperado Dois detalhes úteis na leitura dos campos recebidos: - **Um evento traz mais de uma entidade.** Um evento de deal carrega as propriedades do deal e do contato associado. O nome técnico embaixo de cada linha diz de qual entidade vem cada valor (deals., contacts., leads.) - **Campos de lista suspensa mostram o rótulo, não o código.** Se a propriedade no HubSpot é uma seleção, a Nuvia troca o valor interno pelo texto que você vê no HubSpot Nota os blocos de campos são carregados só quando você abre o evento — por isso o painel mostra **“Carregando os campos deste evento…”** por um instante. Se a carga falhar, aparece o aviso **“Não foi possível carregar os campos deste evento”** com o botão **Tentar novamente**: a falha é de carregamento, não significa que o evento ficou sem dados. #### Buscar um evento pelos IDs do contato, da conversa ou do HubSpot O campo de busca do histórico deixou de procurar só por nome e telefone. Agora o texto que você digita é comparado também com os identificadores gravados em cada evento: - **ID do contato na Nuvia** → traz todos os eventos daquele contato, inclusive os de deal e de lead associados a ele - **ID da conversa na Nuvia** → traz os eventos ligados àquela conversa - **ID do contato no HubSpot** → traz os eventos daquele contato, mesmo quando o objeto principal do evento era um deal ou um lead - **ID do deal no HubSpot** e **ID do lead no HubSpot** → trazem os eventos daquele deal ou lead - Nome ou telefone do contato continuam funcionando como antes O texto de exemplo do campo mudou para **“Buscar por nome, telefone, conversa ou ID…”** para refletir isso. Bom saber os identificadores ficam gravados no próprio evento no momento em que ele acontece. Eventos antigos, registrados antes desta mudança, podem não ter todos os IDs preenchidos, nesses casos a busca por nome ou telefone continua sendo o caminho. #### Filtrar só pelas falhas O seletor de **tipo de evento** passou a listar também os eventos de falha, que antes não apareciam na lista e por isso não podiam ser isolados: - Falha na sincronização de contato - Falha na criação de deal - Falha na atualização de etapa do deal - Falha na sincronização de campos - Falha na criação de lead - Falha na atribuição de proprietário - Falha no envio da transcrição Use esse filtro quando quiser ver só o que deu errado, sem precisar percorrer os registros de sucesso. #### Compartilhar um histórico já filtrado Os filtros do histórico agora ficam registrados no endereço da página. Isso significa que: - Ao aplicar busca, tipo de evento, direção, status ou tipo de objeto, o endereço no navegador é atualizado sozinho - Você pode **copiar o endereço e mandar para outra pessoa**, ela abre exatamente a mesma lista filtrada - Voltar à página por um endereço salvo restaura os filtros que estavam aplicados - O endereço também guarda em qual aba das configurações do HubSpot você está e qual conta está selecionada. Se a empresa tem **uma única conta** conectada, o endereço funciona mesmo sem indicar a conta ### Ir do contato direto para o histórico de sincronização Na aba de campos do contato, tanto no painel da conversa no Inbox quanto no painel de contato, a seção **HubSpot** ganhou um ícone de **relógio com seta** (histórico) ao lado dos IDs. Clicar nele abre, em uma nova aba, o **Histórico** do HubSpot já filtrado por aquele contato. É o caminho mais curto para responder “o que a Nuvia mandou e recebeu sobre este contato?” sem passar por Configurações e sem montar o filtro na mão. - **Quando o ícone aparece:** só quando o contato tem algum vínculo com o HubSpot (ID de contato, deal ou lead) **e** seu perfil tem permissão de visualizar configurações - **Onde aparece:** uma vez por contato, no **ID do Contato** quando ele existe; caso contrário, no ID do Deal ou do Lead - **O que o filtro traz:** todos os eventos do contato, sem separar por tipo de objeto, deals e leads associados entram junto Dica se o ícone de histórico não aparecer para você, confira com o administrador se o seu perfil tem acesso a **Plataforma > Integrações**. Sem essa permissão o painel do HubSpot é inacessível e o atalho fica oculto de propósito. ### Abrir contato ou deal direto no HubSpot a partir de uma conversa Com a integração ativa, um ícone de link externo aparece na aba de campos do contato dentro do módulo **Conversas**. Isso permite abrir o contato ou deal correspondente diretamente na interface do HubSpot, sem precisar sair da Nuvia e buscar manualmente. #### Como usar 1. Abra uma conversa no módulo **Conversas** 2. Clique em Ver detalhes abaixo do nome do usuário 3. No painel lateral direito, clique na aba **Dados** 4. Localize a seção **HubSpot** ao final da tela – ela aparece quando o contato está vinculado a um registro no HubSpot 5. Ao lado do **ID do Contato** ou do **ID do Deal**, clique no ícone de link externo (ícone de quadrado com seta) 6. O perfil do contato ou o deal abrirá diretamente no HubSpot em uma nova aba Dica o ícone de link externo só aparece quando sua conta HubSpot está conectada e o portal ID está configurado corretamente. Se o ícone não aparecer, verifique se a integração está com status **Conectado** em **Plataforma > Integrações > HubSpot**. ## Perguntas frequentes **Quantas vezes a Nuvia sincroniza dados com HubSpot?** A sincronização é em tempo real, orientada por eventos. Quando algo muda no HubSpot, um webhook notifica a Nuvia instantaneamente. Não há intervalo configurável. Conectar a conta, porém, não faz carga inicial: só passa a valer o que muda a partir dali. **Se eu deleto um contato na Nuvia, ele é deletado no HubSpot?** Não. Deleções não são propagadas em nenhuma direção. Se precisar remover dados de ambas as plataformas (ex: solicitação LGPD), você deve deletar manualmente em cada uma. **Posso sincronizar apenas alguns campos, não todos?** Sim. Na aba Campos, você escolhe exatamente quais campos deseja sincronizar. Campos não mapeados não serão sincronizados. **Configurei o DDI padrão e os telefones continuam saindo errados no HubSpot. Por quê?** Porque o DDI padrão só age nos números que **chegam do HubSpot**. No sentido de saída, a Nuvia envia o DDI e o número exatamente como estão gravados no contato. A correção é no cadastro do contato na Nuvia. **O link externo para o HubSpot dentro da conversa aparece para todos os usuários?** Sim, o ícone de link externo aparece para qualquer usuário que tenha acesso à conversa, desde que a integração HubSpot esteja ativa e o contato esteja vinculado a um registro no HubSpot. Já o ícone de **histórico de sincronização** é diferente: ele exige permissão de visualizar configurações, porque leva para dentro do painel de Integrações. **Busquei pelo ID do contato no histórico e não veio nada. Por quê?** Os identificadores são gravados no evento no momento em que ele acontece. Eventos registrados antes dessa mudança podem não ter o ID preenchido, tente pelo nome ou telefone do contato. Lembre também que os logs são mantidos por apenas 7 dias. **Se eu mudar o owner de um contato no HubSpot, o atendente na Nuvia muda automaticamente?** Só se o toggle **Atualizar o owner quando o Contact/Deal for atualizado no HubSpot** estiver ativado na aba **Avançado**, e a **Fonte de sincronização** estiver configurada na aba **Usuários**. Quando ativado, a Nuvia atualiza o atendente da conversa aberta do contato, mantendo o mesmo agente ou IA respondendo (sem transferir o atendimento). **A sincronização de owner afeta conversas já fechadas?** Não. A Nuvia só atualiza conversas com status **Aberta** no momento do webhook. Conversas fechadas ou resolvidas não são alteradas, mesmo que o owner do HubSpot mude. **E se eu tiver múltiplas contas HubSpot?** Atualmente, a Nuvia suporta uma única conta HubSpot por workspace. Se precisar conectar múltiplas contas, será necessário criar workspaces Nuvia separados. **A integração HubSpot funciona com o módulo de Campanhas?** Parcialmente. Eventos do HubSpot podem disparar campanhas automaticamente na Nuvia via webhooks. A Nuvia não envia dados de performance das campanhas de volta ao HubSpot, esses dados ficam visíveis apenas nos Painéis da Nuvia. **Posso exportar o histórico de sincronização para auditoria?** Não. O histórico está disponível apenas para consulta na interface, com filtros por tipo, direção, status e objeto e também pelo endereço da página, que você pode copiar e compartilhar já filtrado. Lembre-se de que os logs são mantidos por apenas 7 dias. [PróximoComo sincronizar contatos e deals entre Nuvia e HubSpot](https://nuvia.ai/docs/artigos/14590403-como-sincronizar-contatos-e-deals-entre-nuvia-e-hubspot) Este artigo ajudou? ## Artigos relacionados - [Como disparar templates WhatsApp na Nuvia direto de um workflow do HubSpot](https://nuvia.ai/docs/artigos/15879535-como-disparar-templates-whatsapp-na-nuvia-direto-de-um-workflow-do-hubspot) - [O que a Nuvia sincroniza com o HubSpot e quando](https://nuvia.ai/docs/artigos/16473526-o-que-a-nuvia-sincroniza-com-o-hubspot-e-quando) - [Como mapear campos entre a Nuvia e o HubSpot](https://nuvia.ai/docs/artigos/16474177-como-mapear-campos-entre-a-nuvia-e-o-hubspot) - [Solução de problemas da integração com HubSpot](https://nuvia.ai/docs/artigos/16474434-solucao-de-problemas-da-integracao-com-hubspot) [Hubspot](https://nuvia.ai/docs/colecoes/19431232-hubspot) 1. [Como configurar integração com HubSpot](https://nuvia.ai/docs/artigos/14501908-como-configurar-integracao-com-hubspot) 2. [Como sincronizar contatos e deals entre Nuvia e HubSpot](https://nuvia.ai/docs/artigos/14590403-como-sincronizar-contatos-e-deals-entre-nuvia-e-hubspot) 3. [O que a Nuvia sincroniza com o HubSpot e quando](https://nuvia.ai/docs/artigos/16473526-o-que-a-nuvia-sincroniza-com-o-hubspot-e-quando) 4. [Como mapear campos entre a Nuvia e o HubSpot](https://nuvia.ai/docs/artigos/16474177-como-mapear-campos-entre-a-nuvia-e-o-hubspot) 5. [Solução de problemas da integração com HubSpot](https://nuvia.ai/docs/artigos/16474434-solucao-de-problemas-da-integracao-com-hubspot) 6. [Como disparar templates WhatsApp na Nuvia direto de um workflow do HubSpot](https://nuvia.ai/docs/artigos/15879535-como-disparar-templates-whatsapp-na-nuvia-direto-de-um-workflow-do-hubspot) 7. [Como inscrever leads/contatos em campanhas da Nuvia direto de um workflow do Hubspot](https://nuvia.ai/docs/artigos/15879734-como-inscrever-leads-contatos-em-campanhas-da-nuvia-direto-de-um-workflow-do-hubspot) ## Ainda precisa de ajuda? Clientes falam com o suporte pelo chat dentro da plataforma. Ainda não é cliente? Fale com o nosso time. [Falar com o suporte na plataforma](https://app.nuvia.ai) [Ainda não sou cliente](https://nuvia.ai/contact) --- Source: https://nuvia.ai/docs/artigos/14501908-como-configurar-integracao-com-hubspot