Cada conversa no Codewo nasce vinculada a um contato — a pessoa (ou empresa) do outro lado. Saiba quais dados o sistema guarda, como criar contatos manualmente, e como eles são criados automaticamente quando chega mensagem nova.
O que é
Contato é o "cadastro do cliente" no Codewo. Cada contato tem um perfil único e centraliza:
- Conversas em todos os canais (WhatsApp, Email, Telegram, WebChat, etc.).
- Cards do CRM em workspaces.
- Eventos da Agenda vinculados.
- Histórico completo de interações.
- Touchpoints de atribuição (de onde veio cada toque).
Quando o mesmo cliente fala com você por WhatsApp e por Email, ele é um contato só — desde que o telefone e/ou email batam.
Campos disponíveis
O cadastro de contato tem campos divididos em blocos:
Identificação:
- Nome, Email, Telefone, Avatar, Data de nascimento, Gênero.
- Documento (CPF ou CNPJ) — sistema detecta o tipo pelo número de dígitos.
- Tipo: Pessoa Física ou Jurídica.
Dados de empresa (quando é PJ):
- Razão social, Nome fantasia, CNPJ, Cargo na empresa.
- Tamanho da empresa, Setor.
- Inscrições estadual e municipal.
- Responsável (nome, telefone, email).
- Email financeiro.
Endereço:
- Logradouro, número, complemento, bairro, CEP, cidade, estado, país.
Operacionais (Codewo):
- Status (Ativo, Inativo, Bloqueado).
- Origem (source do lead — vem da atribuição automática).
- Tags (várias).
- Responsável atribuído (qual atendente é dono da relação).
- Notas internas.
Personalizados: Campo metadata (JSON livre). Sistema guarda dados extras quando enviados via integração — não há UI hoje pra você definir "campos customizados" no cadastro do contato. Pra info extra, use tags + notas internas.
Ações rápidas na página de Contatos
Além do botão "Novo Contato" tradicional, a página Contatos tem 3 ações que aceleram o dia a dia:
- Rápido (ícone raio) — Cria contato em 3 campos só (nome, email/telefone, tags). Útil pra cadastrar alguém no meio de uma conversa sem preencher ficha inteira. Você complementa depois.
- Smart Merge (ícone sparkle) — Detecta contatos duplicados automaticamente e te ajuda a unir.
- Link Rastreável (ícone link) — Gera URL pública que rastreia origem quando o cliente clica.
E o toggle Mostrar deletados no topo da página exibe contatos que foram excluídos (soft-delete), com botão de restaurar por linha ou em lote.
Como criar manualmente
Em Contatos → Novo contato:
- Nome (obrigatório) — Mesmo que "Cliente X" temporário.
- Email e/ou Telefone — Pelo menos um. Sem isso, contato fica difícil de relacionar a conversa.
- Tipo (PF/PJ) — Define quais campos adicionais aparecem.
- Documento (CPF/CNPJ) — Opcional. Se você digitar 11 dígitos, sistema marca PF; 14 dígitos, marca PJ.
- Outros campos — Preencha conforme necessidade. Tudo é opcional além do nome.
- Salve.
Como contatos são criados automaticamente
Maioria dos contatos no Codewo NÃO é criada manualmente — eles nascem da primeira mensagem que chega.
| Canal | O que vira contato |
|---|---|
| WhatsApp (Cloud ou Web) | Telefone do remetente vira novo contato se ainda não existir |
| Telegram | Username + ID do Telegram |
| Endereço do remetente | |
| WebChat | Visitante anônimo até preencher form |
| Instagram DM / Facebook | ID do perfil |
Quando você cria contato manualmente com telefone X e depois chega mensagem WhatsApp do telefone X, o sistema vincula automaticamente — não duplica.
Importando contatos
Status atual: o Codewo tem hoje um importador CLI específico pra contatos de WhatsApp (telefones do seu próprio WhatsApp). Importação genérica de CSV pela interface ainda não é exposta direto na UI.
Pra trazer uma lista grande de leads doutro lugar (planilha do Excel, exportação de outro CRM, etc.), as opções práticas hoje são:
- API pública — Crie API Key com scope
contacts:writee use o endpoint REST pra cadastrar em lote. Cada POST cria um contato. Ver API Keys. - Manual — Pra listas pequenas (até ~50), digitar mesmo.
- Suporte — Listas grandes, fale com contato@codewo.com.br — em alguns casos a equipe importa pra você.
Status do contato
- Ativo — Aparece em listas, recebe mensagens normalmente.
- Inativo — Some das listas de seleção mas histórico fica. Útil pra "ex-cliente".
- Bloqueado — Mensagens novas dele são silenciadas. Útil pra spammers ou clientes problemáticos. Não recebe broadcast.
Pegadinhas comuns
- Cadastro novo manualmente vincula canais sozinho. Quando você cria contato com telefone X, o sistema vincula automaticamente os canais WhatsApp da empresa a ele. Significa que se você criar contato "teste" com seu próprio telefone, qualquer mensagem que você mandar pra empresa cai como vinda dele. Use telefones reais.
- Documento errado vira tipo errado silenciosamente. Se você digita 14 dígitos no CPF (deveria ser 11), sistema marca como PJ. Confira tipo depois de digitar documento.
- Excluir contato é soft-delete. Contato "excluído" some das listas mas continua no banco. Pra recuperar, ligue o toggle Mostrar deletados no topo da página de Contatos — botão "Restaurar" aparece nas linhas dos excluídos. Dá pra restaurar em lote também (selecione vários e use a ação em massa).
- Tags ≠ campos. Não tem como criar campo "Plano contratado" customizado e filtrar por valor. Mas dá pra criar tag "Plano-Pro" e filtrar por tag. Tag é a maneira simples de adicionar atributo categórico.
- Duplicados? Use Smart Merge. Se você acaba com 2 contatos pro mesmo cliente (cadastrados com email e telefone diferentes, ou criados em canais diferentes antes de você perceber), o botão Smart Merge detecta e une. Não saia "limpando manualmente" deletando o duplicado — usar o merge preserva histórico unificado.
- Metadata é caixa-preta. Dados em
metadata(vindos via API) não aparecem na ficha visual — você só vê via API ou exportação. Não conte com isso pra atendimento humano.
Exemplo prático
Operação B2B vendendo software:
- Lista de leads inbound vem por WhatsApp. Cliente novo manda mensagem → contato criado automaticamente com nome do WhatsApp dele.
- Atendente abre a conversa, vê contato sem email. Pergunta "qual seu email pro envio da proposta?" e atualiza o cadastro.
- Após conversa qualificada, atendente preenche CNPJ, razão social, cargo (Diretor / Comprador / TI), tamanho da empresa.
- Marca tag "Lead-Quente" e cria card no Pipeline Vendas vinculado ao contato.
- Conversão: muda status pra "Cliente-Pro", troca tag "Lead" por "Cliente-Pro".
Esse contato agora tem todas as conversas, todas as oportunidades, todo o histórico — num lugar só.
Boas práticas
- Tag pra categoria, campo pra dado único. Tag "Cliente-VIP", campo "Cargo".
- Mantenha email cadastrado — Mesmo se o canal principal é WhatsApp. Email é o vínculo mais estável (telefone muda; email tipicamente não).
- Use Notas internas pra contexto. "Cliente sensível a preço", "Já reclamou com o CEO uma vez". Ficam visíveis pra equipe interna.
- Audite contatos sem origem. Em Contatos → filtros, ver quem tem origem "direct" pode indicar perda de atribuição em algum canal.
- Bloqueie spammers em vez de excluir. Excluir cria buraco no histórico; bloquear silencia futuro sem perder o que aconteceu.