Como Importar Contatos em Massa via CSV
Este artigo orienta sobre como importar contatos no Cloud Chat usando CSV, fornecendo contexto sobre quando e por que
usar esse recurso.
https://www.loom.com/share/35167101ea694bb0820b0a940e373900
Lembrete: também dá pra fazer isso de forma automática via API (FAQ sobre isso aqui).
Acesse o template de import de contatos
No Cloud Chat, a importação de contatos é uma tarefa simples. Primeiro, vamos olhar um template desse CSV.
Acesse a seção de contatos no menu esquerdo principal e clique em importar.
Aqui, é possível baixar um template de CSV que já contém alguns exemplos de contatos.
O CSV fica como o exemplo abaixo:
Detalhes importantes sobre as informações no CSV
Observe que essas são as colunas padrões que vem no template, mas, como verá abaixo, dá pra você adicionar mais colunas
como tags e campos personalizados.
Para saber como criar campos personalizados, veja essa FAQ.
Importante: os campos que determinam um contato único são o telefone, o e-mail e o identificador (identifier). Ou seja,
pelo menos um desses campos precisa estar sempre presente.
O próximo passo é selecionar as colunas que você quer preencher ou alterar. Podem ser as colunas que vem no template ou
outras informações de contato como tags e campos personalizados.
Importante: as colunas que não deverão ser alteradas devem ser deletadas, com exceção dos campos verificadores - email,
telefone ou identifier.
Agora preencha as informações na coluna que você deseja adicionar ou alterar.
Sobre campos em branco: o comportamento depende do tipo de campo:
- Nome e campos padrão: se você deixar em branco, o valor existente será apagado.
- Campos personalizados (custom attributes): campos em branco são ignorados — o valor existente é preservado. Somente
campos preenchidos serão atualizados.
- Tags: não substituem valores, mas sim adicionam novas tags ao contato. Para aprender como fazer deleção de tags em
massa, utilize nossa API de deleção de tags (FAQ aqui) ou entre em contato com nosso time de suporte.
- Email, telefone e identifier (quando não são a chave de match): se estiverem em branco, o valor existente é
preservado.
Garanta que os telefones estão com código internacional e o "9" na frente
Um erro comum que nossos clientes cometem é esquecer de incluir o código de país ao adicionar contatos. Para o Brasil,
esse código é +55. Essa omissão pode levar a problemas de duplicidade. Por isso, ao importar seus contatos,
certifique-se de inserir o código de país corretamente.
Outro equívoco frequente é não colocar o número 9 na frente dos números de telefone, já que, atualmente, todos os
números de celular no Brasil têm esse dígito inicial. Isso pode causar não apenas duplicidades indesejadas, mas também
impactar negativamente a eficácia das suas campanhas proativas no WhatsApp.
Ex.: +5511960832431 (o +55 é o código de país e o primeiro 9 foi adicionado pela Anatel há alguns anos atrás).
Nota técnica: o sistema possui normalização automática de telefones brasileiros — se você enviar um número com +55 mas
sem o 9 (ex: +551160832431), o sistema adicionará o 9 automaticamente. Porém, recomendamos fortemente que você já inclua
o 9 no CSV para evitar qualquer ambiguidade.
O que acontece na prática ao importar os contatos?
Na prática, o que acontece é que:
- O sistema buscará se o contato já existe: o sistema procura pelo email, identifier e telefone nessa ordem de
prioridade. Se encontrar um contato existente por qualquer um desses campos, entenderá que se trata do mesmo
contato.
1. Se ele não encontrar, criará um novo: caso o email, telefone ou identifier não for encontrado, ele criará um
contato novo.
2. Se encontrar, alterará as informações: as informações serão atualizadas conforme as regras de campos em branco
descritas acima.
Atenção — divergência de identificadores: se o seu CSV contiver um contato com email e telefone que apontem para
contatos diferentes já existentes no sistema, essa linha será rejeitada para evitar conflitos. Exemplo: se o email
[email protected] pertence ao contato A, mas o telefone +5511960832431 pertence ao contato B, o sistema não saberá qual
contato atualizar e ignorará essa linha. Nesse caso, recomendamos corrigir a divergência manualmente antes de
reimportar.
Linhas duplicadas no CSV
Se o seu CSV contiver duas ou mais linhas com o mesmo email, telefone ou identifier, apenas a primeira linha será
processada. As demais serão rejeitadas como duplicatas. Isso vale mesmo que as outras informações (nome, tags, etc.)
sejam diferentes entre as linhas.
Dica: antes de importar, revise seu CSV para garantir que não há linhas duplicadas referenciando o mesmo contato.
Como adicionar mais informações (colunas) como tags e campos customizados
Você pode editar qualquer informação de contato. Isso se faz adicionando a chave do campo como título de uma nova
coluna.
Se quiser adicionar uma tag nova, basta criar uma coluna e colocar o título da coluna como "tags" e preencher em cada
célula a tag que deseja colocar. Nesse exemplo, colocamos a tag "bug" nos contatos.
Para tags, é importante que seja uma tag já existente. Se ela não existir, sua importação falhará.
É possível criar tags diretamente na aba de contatos ou dentro de configurações > tags.
Outra possibilidade é preencher atributos personalizados, campos que você mesmo criou. Para descobrir o nome desse campo
no nosso banco de dados, é só ir até os atributos customizados de contato e copiar o nome da chave desse campo.
Agora vamos subir o import de contatos no Cloud Chat
Depois de preencher a planilha, salve-a como CSV. Depois volte à seção de importação, escolha o arquivo e clique em
importar.
Quando o sistema concluir a importação (pode levar até meia hora), você receberá uma mensagem de sucesso no seu e-mail,
inclusive com o número de sucessos e falhas.
⚠️ IMPORTANTE: garanta que seu arquivo CSV está configurado com encoding UTF-8 para evitar erros na importação como
gerar caracteres inválidos ou ainda não encontrar tags para o contato pois sua tag está diferente do que foi
pré-configurado.
