Cliente avisou: "agora meu WhatsApp é outro número". Ou pior: ele já mandou mensagem do número novo e o bot criou um perfil duplicado. Como resolver?
A regra que ajuda você: cliente_id é UUID
A Kontato vincula histórico ao cliente_id (UUID interno), não ao telefone. Atualizar telefone do cadastro não invalida histórico:
- Agendamentos passados continuam vinculados
- Conversas continuam vinculadas
- Cartão fidelidade continua
- Pagamentos continuam
Telefone é a chave primária de identificação (CLAUDE.md regra do projeto), CPF é secundária. Mas internamente tudo é UUID.
Caso A — Cliente avisa ANTES de mandar mensagem
Cenário ideal. Cliente te liga ou WhatsApp Web/SMS pelo número antigo: "vou trocar pra YY YYYYY-YYYY".
Resolução simples:
- Acesse
/clientes/[id]do cliente - Click "Editar"
- Atualize o Telefone pro número novo
- Salve
Sistema:
- Normaliza o telefone (digitos + prefix
55) - Mantém o
cliente_id(UUID) intacto - Histórico continua todo lá
- Próxima mensagem do número novo bate no perfil já cadastrado → bot reconhece como cliente conhecido
Caso B — Cliente já mandou mensagem do número novo
Pior cenário. Bot recebeu mensagem do WhatsApp com telefone novo, não bateu com nenhum cliente existente, criou perfil novo. Agora você tem 2 perfis pra mesma pessoa.
⚠️ Não há ferramenta nativa de merge. F89 (Merge de clientes) foi removido por complexidade — juntar histórico de pagamentos, fidelidade, agendamentos e conversas automaticamente é arriscado. A solução é manual.
Workaround manual
1. Decidir qual perfil manter (geralmente o antigo, pra preservar histórico). O perfil novo provavelmente tem 1 ou 2 mensagens só.
2. No perfil ANTIGO:
- Click "Editar"
- Atualizar Telefone pro número novo
- Em Notas anotar:
Número anterior: XX XXXXX-XXXX (trocou em DD/MM/2026) - Salvar
3. Conferir: agora o perfil antigo tem o telefone novo. Mas o perfil novo ainda existe com o mesmo telefone → conflito de 2 cadastros com mesmo telefone.
4. No perfil NOVO (o duplicado):
- Click "Editar"
- Apague o telefone ou troque pra placeholder vazio (pra liberar o número)
- Considere deletar o perfil novo (soft delete preserva auditoria)
⚠️ Histórico do perfil novo (a 1-2 mensagens iniciais) se perde. Limitação real do workaround.
Ordem importa
Se você inverte (atualiza o telefone do antigo antes de liberar o do novo), o sistema pode rejeitar (constraint unique) ou aceitar mas criar 2 cadastros com mesmo telefone (raro).
A ordem correta:
- Anota o número novo num bloco de notas
- Apaga/troca o telefone do perfil novo primeiro
- Atualiza o telefone do perfil antigo depois
- Deleta o perfil novo
CPF como chave secundária
Se você tem CPF cadastrado em ambos os perfis, é fácil confirmar que são a mesma pessoa antes de fazer o merge manual. Recomendado pedir CPF no cadastro pra clientes recorrentes — facilita identificar duplicidade.
Edge cases
Cliente tem CPF + telefone novo
Bot deveria reconhecer pelo CPF mas hoje (v0.28.x) a chave primária do bot é telefone — cria perfil novo mesmo se CPF coincide. Limitação atual.
Cliente nunca mais vai usar o número antigo
Pode deletar o perfil antigo, mas:
- Histórico junto vai
- Não recomendado a menos que o perfil antigo tenha quase nada de relevante
- Mais seguro: manter perfil antigo, atualizar telefone, deletar o novo
2+ perfis diferentes pra mesma pessoa por trocas múltiplas
Decisão difícil:
- Manter o mais rico em histórico (geralmente o original)
- Anotar todos os telefones antigos nas notas
- Deletar os outros
Cliente mandou áudio do número novo logo de cara
Áudio passa por Whisper antes do bot processar. Mesmo cenário do Caso B — sistema recebe a mensagem, telefone não bate, perfil novo é criado. Workaround idêntico.
Cliente troca, volta atrás (volta pro número antigo)
Você atualizou pro novo, ele desistiu, voltou pro original. Edita o cadastro de novo, troca pro original. Histórico não é perdido.
Maridos/esposas usando o mesmo WhatsApp
Não trate como número trocado. Crie 2 cadastros distintos (mesmo telefone) com nomes diferentes. Histórico de cada um fica separado pelo cliente_id. Mensagens chegam misturadas — você decide pelo contexto qual cliente é.
Por que não tem merge automático?
F89 (Merge de clientes) foi planejado mas removido por:
- Complexidade: histórico envolve agendamentos, pagamentos, fidelidade, tags, conversas, push notifications, NPS — joinar tudo sem perder nada é arriscado
- Edge cases: o que faz com 2 cartões fidelidade ativos? 2 agendamentos no mesmo dia? 2 valores diferentes de "última visita"?
- Decisão humana: muitas vezes não é claro qual perfil é o "verdadeiro" — alguns dados são contraditórios
A solução manual é mais lenta mas segura.
Prevenção
- Mantenha CPF cadastrado em clientes recorrentes
- Pergunte sempre se cliente trocou número quando notar perfil duplicado
- Eduque sua equipe: "se cliente avisar que vai trocar, atualiza na Kontato ANTES de ele mandar mensagem do número novo"
Próximos artigos
- Cliente não recebe — outro problema de WhatsApp
- Bot não agenda — problemas no fluxo de agendamento
- Visão geral do troubleshooting