Como configurar integração com 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

---

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

---

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

---

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

---

Configurações da aba Avançado

Além do DDI padrão, a aba Avançado concentra as regras de sincronização da conta.

---

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)

---

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)

---

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

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

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.

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

---

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

---