HubSpot

Esta página é para quem já usa HubSpot e quer que o lead capturado pelo agente chegue lá sem ninguém digitar. É uma integração de mão única: o ChatMade escreve no HubSpot e nunca lê a sua base.

O que você precisa antes

• Uma conta HubSpot com permissão de instalar aplicativo.
• Um administrador do ChatMade com a permissão manage_organization.
• Numa instalação própria, as variáveis HUBSPOT_CLIENT_ID e HUBSPOT_CLIENT_SECRET preenchidas no .env do backend, com a URL de retorno {BACKEND_URL}/api/v1/crm/hubspot/callback registrada no aplicativo criado em developers.hubspot.com. Sem isso, o botão de conectar devolve “HubSpot app credentials are not configured”.

Bom saber: você não cola client id nem client secret no painel. Não existe formulário de credencial na tela do CRM. O aplicativo é do servidor, e a autorização acontece por OAuth.

Conectar

1. No painel, vá em Settings → Integrations (“Configurações → Integrações”).
2. Ache o cartão HubSpot, com a etiqueta CRM e a descrição “Push captured leads into HubSpot as contacts, deduped by email, with the AI summary attached.”
3. Clique em Connect (“Conectar”). O navegador vai para a tela de autorização do HubSpot.
4. Autorize. O ChatMade pede dois escopos, e só eles: crm.objects.contacts.read e crm.objects.contacts.write.
5. Você volta para as integrações com a confirmação “HubSpot connected successfully!”.

O cartão passa a mostrar a etiqueta Connected (“Conectado”) e o domínio do seu portal, mais os botões Manage (“Gerenciar”) e Disconnect (“Desconectar”).

Manage não abre configuração nenhuma: é um teste de conectividade somente-leitura, que responde com um aviso do tipo “Connected to {nome da conta}”. Ele não escreve nada no seu HubSpot.

Se a autorização for cancelada, você lê “HubSpot connection was cancelled”. Se o portal já estiver ligado a outra organização, “Failed to connect to HubSpot: account connected elsewhere”.

Apontar o agente para o HubSpot

Conectar não basta. Cada agente escolhe o destino:

1. Main Menu → AI Agents (“Menu principal → Agentes de IA”), abra o agente.
2. Aba Lead Capture (“Captura de leads”), seção When a lead qualifies (“Quando um lead qualifica”).
3. Escolha HubSpot.
4. Save changes (“Salvar alterações”).

O que é criado no HubSpot

Exatamente dois objetos, nesta ordem:

1. Um Contato. Criado ou atualizado por upsert, com o e-mail como chave de deduplicação — quem faz a deduplicação é o próprio HubSpot. As propriedades enviadas são email, firstname, lastname, phone, company e lifecyclestage: lead. Propriedade vazia não é enviada.

O nome é dividido de forma simples: tudo menos a última palavra vira o primeiro nome, a última palavra vira o sobrenome.

2. Uma Nota, associada a esse contato. A nota é HTML e tem esta forma:

Lead captured by ChatterMate
AI summary: {o resumo escrito pela IA}
{Rótulo do seu campo}: {resposta}
Captured on: {link da página onde a conversa aconteceu}

Só a primeira linha é obrigatória. Os campos customizados aparecem pelo rótulo que você escreveu na captura. E-mail, nome, empresa e telefone não se repetem na nota — eles já estão no contato.

A nota é feita em melhor esforço: se ela falhar, o contato continua criado.

Bom saber: o objeto Leads do HubSpot não é usado, de propósito — ele exige um proprietário com licença paga e um contato pré-existente, o que não combina com captura em conversa. O que você recebe é Contato mais Nota.

Envio numa direção só

Esta é a parte que interessa a quem se preocupa com segurança da base.

O ChatMade tem exatamente cinco operações com o HubSpot: gerar a URL de autorização, trocar o código por token, renovar o token, enviar o lead e revogar o token. Mais o teste de conectividade, que é leitura.

Não existe importar, listar, sincronizar de volta ou apagar. Nada do seu HubSpot é lido para dentro do ChatMade — as únicas leituras são a checagem de identidade e a busca de deduplicação feita imediatamente antes de gravar. Do envio, ficam guardados só o id do contato e o link do registro.

Atenção: um detalhe honesto. Quando o e-mail bate com um contato que já existe, o envio atualiza aquele contato. E o upsert do HubSpot sobrescreve um firstname, phone ou company já preenchido se o ChatMade tiver capturado um valor diferente. Ele não apaga campo — campo vazio não é enviado —, mas substitui valor conflitante. Se isso for um problema para você, avalie o Pipedrive, cujo envio só preenche o que estiver em branco.

Enviar uma pessoa à mão

Em Main Menu → People (“Menu principal → Pessoas”), abra a ficha da pessoa. No topo, acima de “Mark as customer”, há três estados possíveis:

Situação	O que a ficha mostra	Botão
Nenhum CRM conectado	No CRM connected.	Connect (“Conectar”)
Conectado, nunca enviado	Not synced to HubSpot yet.	Sync now (“Enviar agora”)
Já enviado	Synced to HubSpot · {data} e o link View in CRM ↗	Re-sync (“Enviar de novo”)

Sem e-mail, o botão fica desligado com a dica “Add an email first — CRM sync dedupes by email”.

Cliques repetidos dentro de 10 segundos são ignorados.

Bom saber: o envio manual vai para todos os CRMs conectados da organização, não só para o que o agente escolheu. Se você tem HubSpot e Pipedrive ligados, o botão manda para os dois.

A fila de envio

O envio automático não é síncrono: ele entra numa fila processada por um worker próprio (o serviço crm_sync do Docker Compose). Cada lead gera um trabalho por CRM, e uma restrição de unicidade impede envio duplicado.

O estado de cada trabalho é um de cinco: pendente, processando, concluído, falhou ou pulado. A fila é lida a cada 10 segundos, em lotes de até 20, e os trabalhos de uma mesma organização são enviados em série para não estourar limite de requisição do CRM.

Falha transitória é repetida até 7 vezes, com espera dobrando a partir de 60 segundos até o teto de 1 hora, mais um pouco de aleatoriedade. Erro 429 respeita o Retry-After que o HubSpot mandar. Erro 4xx que não seja 401 nem 429 é permanente: não repete.

Se o cartão da integração mostrar “⚠️ N leads failed to sync in the last 7 days”, é essa fila falhando.

Quando a conexão morre

O estado da conexão pode ser ativo, expirado (o token de renovação morreu) ou revogado (o aplicativo foi desinstalado do lado do HubSpot).

O token de acesso é renovado sozinho quando faltam menos de 120 segundos para expirar. O token de renovação do HubSpot não tem prazo.

Atenção: na tela, expirado e revogado são indistinguíveis — os dois mostram o mesmo aviso, “⚠️ Connection expired — reconnect to resume lead sync.” Se você desinstalou o aplicativo pelo HubSpot, vai ler “expirada” mesmo assim.

Reconectando, todos os envios que tinham falhado em definitivo voltam para a fila.

Desconectar

Botão Disconnect (“Desconectar”) no cartão. A confirmação lista o que acontece:

• Para de enviar leads (o que está na fila é cancelado)
• Revoga os tokens de acesso do ChatMade
• Mantém a escolha de CRM nos agentes — ela fica inativa até você reconectar

Se você desinstalar o aplicativo pelo lado do HubSpot, um webhook de entrada avisa o ChatMade e a conexão é marcada como revogada automaticamente.

Próximo passo

Se você usa Pipedrive em vez de HubSpot — ou os dois —, veja Pipedrive.