Imagine o mesmo cliente aparecendo duas vezes no seu sistema: uma pelo número antigo, outra por um identificador novo, sem nenhum vínculo entre os dois. O atendente não vê o histórico completo, a automação dispara mensagens repetidas e a análise de dados fica torta. Esse é o cenário que a reconciliação de histórico existe para evitar.
Com a chegada dos usernames e do BSUID no WhatsApp, um cliente passa a ter mais de um identificador. Se cada um virar um contato separado, a base incha, o histórico se fragmenta e a experiência piora sem que ninguém perceba de imediato.
Neste artigo, explicamos o que é a reconciliação de histórico, como fazê-la na prática e quais regras seguir para unir número e BSUID do mesmo cliente sem gerar duplicidade.
O que é a reconciliação de histórico
Reconciliar é reconhecer que número de telefone, BSUID e username podem pertencer à mesma pessoa e uni-los em um único registro. Na transição, a reconciliação histórica de usuários deixa de ser um detalhe e vira estratégia essencial. Isso porque o BSUID é a nova chave estável de identificação.
Há um detalhe crítico de tempo: o Livro de Contatos da Meta, que mapeia número e BSUID, não é retroativo. Segundo a documentação oficial da Meta, ele só registra interações que acontecem depois de ativado. Quanto antes começar, mais completa fica a base de mapeamentos.
Como fazer na prática
O fluxo de reconciliação tem quatro passos. Primeiro, colete os identificadores disponíveis em cada interação: número, BSUID e username. Depois, consulte o mapeamento que liga número e BSUID, apoiado na API de Livro de Contatos da Meta e nos endpoints equivalentes das plataformas de atendimento. Em seguida, vincule os registros do mesmo cliente em um só perfil. Por fim, mantenha esse vínculo atualizado a cada nova conversa.
O webhook que avisa quando o cliente troca de número
Esse é o reforço mais útil que a documentação da Meta ganhou desde a publicação original deste artigo, e ele resolve justamente o caso mais difícil da reconciliação. Quando o cliente troca o número de telefone, o BSUID é regenerado, mas a mudança não chega em silêncio: ela é entregue na assinatura de mensagens como um webhook de sistema, com messages[].type igual a system. O campo system.type vem como user_changed_number quando o novo número pode ser compartilhado com a sua empresa, ou como user_changed_user_id quando só a troca de BSUID pode ser reportada.
O detalhe que faz a diferença está nos campos system.user_id, com o BSUID novo, e system.previous_user_id, com o anterior. Ou seja, a Meta entrega o par antigo e novo de forma explícita. Tratar esse evento é o caminho oficial para costurar os registros em vez de depender de inferência por histórico ou por username, que o cliente pode alterar a qualquer momento.
Vale conhecer também a API de Livro de Contatos, que permite consultar se existe número registrado para um BSUID e remover a entrada quando necessário. Ela é escopada por portfólio de negócios e não sincroniza entre portfólios diferentes, o que importa para quem tem mais de uma operação na mesma marca.
Regras de ouro para não duplicar
| Situação | Risco | Regra |
|---|---|---|
| Cliente chega só com BSUID | Criar um contato novo duplicado | Buscar o BSUID antes de criar o registro |
| Cliente troca de número | Gerar um novo BSUID sem vínculo | Tratar o webhook de sistema e usar o previous_user_id |
| Livro de Contatos recém-ativado | Não ter o mapeamento antigo | Ativar cedo, pois não é retroativo |
Comece agora, porque não é retroativo
A reconciliação é uma corrida contra o relógio: cada dia sem mapear é histórico que você não recupera depois. Por isso ela é uma das frentes centrais do checklist de preparação do CRM. Feita a reconciliação nos bastidores, o próximo elo é a ponta: garantir que atendimento humano e bots enxerguem esse histórico unificado.
- Ative o mapeamento entre número e BSUID o quanto antes.
- Defina uma regra clara de correspondência para unir registros.
- Evite criar contato novo sem antes checar o BSUID existente.
- Monitore duplicidades e corrija de forma contínua.
Perguntas frequentes
O que é reconciliação de histórico no WhatsApp?
É o processo de reconhecer que número, BSUID e username podem ser da mesma pessoa e uni-los em um único registro, preservando o histórico do cliente.
Por que preciso reconciliar?
Porque, sem isso, o mesmo cliente pode virar dois contatos: um pelo número, outro pelo BSUID. Isso fragmenta o histórico e gera mensagens repetidas.
O mapeamento entre número e BSUID é retroativo?
Não. O Livro de Contatos da Meta só registra interações após a ativação. Por isso é importante começar cedo, para acumular o máximo de mapeamentos.
Como evitar contatos duplicados?
Busque o BSUID antes de criar um novo contato, defina regras de correspondência claras e monitore duplicidades de forma contínua na base.
O que acontece se o cliente trocar de número?
Um novo BSUID é gerado e a Meta avisa por um webhook de sistema, que traz o BSUID novo em system.user_id e o anterior em system.previous_user_id. Tratar esse evento é a forma oficial de manter o registro único.
