Registrar as conversas do WhatsApp no HubSpot depende de três decisões: transformar cada mensagem em atividade da linha do tempo do contato, casar o cliente pelo campo certo e entender que registrar conversas no CRM não libera o envio — a janela de 24 horas da Meta define o que pode ser respondido sem template. Com isso resolvido, o vendedor abre o contato e vê o histórico inteiro da negociação, sem depender de prints colados no cadastro. Este guia mostra as três formas de integrar, o erro de formato de telefone que quebra o registro e um checklist de ativação para times de vendas brasileiros.
Como o registro chega ao CRM
Quando o cliente manda mensagem, a integração precisa executar três passos antes de qualquer coisa aparecer no HubSpot: localizar ou criar o contato pelo número, gravar a mensagem como atividade associada a esse contato e atualizar as propriedades comerciais, como o estágio do ciclo de vida. Se qualquer passo falhar, a conversa existe no WhatsApp, mas não no CRM — e o histórico vira um buraco na negociação.
O ponto de falha mais comum é o matching. O HubSpot casa contatos por telefone somente quando o número está gravado exatamente no mesmo formato nos dois lados; se o cadastro tem “11 98888-7777” e a API recebe “+5511988887777”, o sistema tende a criar um contato novo em vez de juntar os registros. Por isso o e-mail continua sendo o identificador único que evita contatos duplicados no HubSpot sempre que você consegue capturá-lo; o telefone é a chave prática do WhatsApp, mas pede normalização desde o primeiro cadastro.
Três formas de integrar
| Método | O que registra | Para quem | Ponto de atenção |
|---|---|---|---|
| Aplicativo pronto do mercado | Mensagens e status na linha do tempo com pouca configuração | Times pequenos sem desenvolvedor | Menos controle sobre formato de telefone e regras de negócio |
| API do HubSpot com webhook da Cloud API | Cada evento do WhatsApp vira atividade ou atualização de propriedade | Times com desenvolvimento próprio | Exige tratamento de erro, reprocessamento e versionamento |
| Automação intermediária, como n8n | Fluxos visuais que leem o webhook e gravam no CRM | Quem quer flexibilidade sem código | Duplicidade de contatos se o fluxo não normalizar o número |
Na rota por API, o endereço base continua o mesmo, mas integrações novas devem apontar para a versão datada mais recente, como a 2026-09, porque a HubSpot publica versões em calendário e mantém as anteriores apenas até a data de fim de vida. Para criar ou atualizar o contato a partir do número do WhatsApp, o pedido vai para o endpoint de contacts com as propriedades de telefone e e-mail; a resposta devolve o ID do registro, que passa a ser a referência para associar todas as mensagens seguintes daquele cliente.
Se você sincronizar em lote uma base histórica de conversas, atenção: operações em lote ficam limitadas a 100 registros por requisição, então a importação precisa ser fatiada e acompanhada requisição por requisição, com retry para os lotes que falharem. Para o lado de entrada dos eventos do WhatsApp, o guia de configuração do webhook da API do WhatsApp mostra como montar a base que vai alimentar o CRM.
O formato do telefone
A documentação da Meta recomenda enviar sempre o sinal de mais e o código do país ao mandar mensagem para um cliente; sem o “+55”, o número pode ser entregue errado ou interpretado como de outro país. Há ainda uma particularidade regional: o Cloud API pode modificar o prefixo extra adicionado ao telefone no Brasil, o que muda o número efetivamente entregue no webhook. Para o HubSpot, isso significa uma regra simples: normalize tudo para o formato E.164 (+5511988887777) antes de gravar, tanto no cadastro quanto no fluxo de integração, e trate o número recebido do webhook antes de usá-lo como chave de busca. Uma planilha de clientes com DDD sem nono dígito é a causa mais frequente de contato duplicado logo na primeira semana de uso.
A janela de resposta da Meta
O registro da conversa não muda a regra de envio: dentro da janela de atendimento, aberta pela última mensagem do cliente, você responde livremente; depois dela, apenas mensagens de template pré-aprovadas. Na prática, o time enxerga o histórico completo no contato do HubSpot, mas precisa agir rápido — se a negociação esfriar por um dia, a resposta livre acaba. Vale configurar o CRM para sinalizar conversas paradas ainda dentro da janela e treinar o vendedor para capturar o e-mail do cliente enquanto a conversa está aberta, porque é esse dado que garante a deduplicação depois. Quando a resposta precisa sair por template, o custo por atendimento entra na conta: o guia de custo por atendimento na API oficial em reais detalha os valores por categoria de mensagem.
Checklist antes de ativar
- Normalizar todos os números para o formato +55 com DDD e nono dígito antes do primeiro envio de teste.
- Definir a regra de criação de contato: telefone como chave operacional e e-mail capturado na primeira conversa para deduplicação.
- Testar com um número real e conferir se a mensagem aparece como atividade na linha do tempo do contato correto.
- Fatiar importações históricas em blocos menores e monitorar as falhas com retry automático.
- Configurar alerta de conversa parada dentro da janela de atendimento para o time comercial.
- Documentar quem responde pelo WhatsApp e quem registra no CRM quando os dois papéis são de pessoas diferentes.
