Principal Contatos | Cadastro, importação e exportação Como importar contatos em massa via CSV

Como importar contatos em massa via CSV

Última atualização em Sep 02, 2026

Quando usar

  • Você precisa carregar uma base nova de contatos no Cloud Chat

  • Você quer atualizar atributos personalizados de muitos contatos de uma vez

  • Você precisa adicionar tags ou bloquear contatos em massa

Pré-requisitos

  • Estar logado como administrador ou supervisor

  • Ter o arquivo CSV no encoding UTF-8 com pelo menos um identificador (email, telefone ou identifier) por contato

  • Ter um arquivo de no máximo 10 MB

Também é possível fazer essa importação via API. Detalhes em: Como importar contatos em massa via API.

Acessar o template de import

Etapa 1 — Baixar o template

A importação de contatos é simples. Primeiro, baixe um template do CSV.

  1. Acesse a seção Contatos no menu lateral

  2. Clique em Importar

  1. Baixe o template do CSV (já vem com exemplos)

Exemplo do CSV:

Cada tela tem o seu próprio modelo

Reaproveitar o CSV de uma finalidade em outra é a causa mais comum de import ou disparo que falha. Baixe sempre o modelo da tela em que você está:

Finalidade Colunas do modelo
Importar contatos (esta tela) name, email, phone_number, company_name, city, tags
Audiência de campanha por e-mail email, name
Audiência de campanha por telefone phone_number, name
Importar etiquetas name, description, color

Todas as colunas padrão do sistema

O modelo baixado traz só as seis colunas mais usadas, mas o Cloud Chat reconhece onze colunas padrão. Qualquer uma delas pode entrar no CSV mesmo sem estar no modelo — e, por serem reconhecidas, passam direto pela etapa de revisão de colunas.

Coluna O que preenche no contato Detalhes
name Nome Se vier em branco, o nome atual é apagado
email E-mail Chave de identidade. Único na conta
phone_number Telefone Chave de identidade. Único na conta. Sempre no formato internacional (+55...)
identifier Identificador externo (o ID do contato no seu sistema) Chave de identidade. Único na conta. Continua sendo aceito, mas o assistente sugere ignorar — ver Revisar as colunas
blocked Bloqueio do contato true, 1, yes, t, on / false, 0, no, f, off
company_name Nome da empresa do perfil Gravado em atributos adicionais e personalizados (dual-write)
company Empresa (formato legado) Não aparece no campo "Nome da empresa" do perfil. Prefira company_name
city Cidade Dual-write, igual a company_name
tags Etiquetas Lista separada por vírgula. Adiciona, não substitui
tags_add Etiquetas Equivalente a tags
tags_remove Etiquetas Remove as etiquetas listadas

Qualquer coluna fora dessa lista é tratada como campo personalizado — você decide o destino dela na etapa Revisar as colunas, mais abaixo.

Os nomes das colunas diferenciam maiúsculas de minúsculas. email é reconhecido; Email ou E-mail, não — viram coluna desconhecida e caem na etapa de revisão (onde ainda dá para mapear para o campo certo). Escreva os cabeçalhos exatamente como na tabela, em minúsculas.

O arquivo pode ser separado por vírgula (,) ou ponto e vírgula (;) — o sistema detecta pelo cabeçalho. Espaços em volta do nome da coluna são ignorados (email funciona igual a email).

Detalhes importantes sobre o CSV

O modelo vem com um subconjunto das colunas padrão (a lista completa está acima) — e você pode adicionar mais colunas (tags, campos personalizados). Colunas que o Cloud Chat não reconhece não viram mais campo personalizado automaticamente: você decide o que fazer com cada uma na etapa Revisar as colunas, mais abaixo. Para criar campos personalizados antes: Como criar campos customizados de contatos e conversas.

Os campos que determinam um contato único são telefone, e-mail e identificador (identifier). Pelo menos um precisa estar sempre presente.

As colunas que não devem ser alteradas devem ser deletadas, com exceção dos campos chave (email, telefone ou identifier).

Comportamento de campos em branco

Campo Comportamento se em branco
Nome e campos padrão O valor existente é apagado
Campos personalizados Campos em branco são ignorados — valor existente é preservado
Tags Não substituem — adicionam (ver abaixo)
Email/telefone/identifier (quando não são chave) Valor existente é preservado

Tags — 3 formatos

  • tags (recomendado) — lista separada por vírgulas. Adiciona ao conjunto existente (não remove tags presentes)

  • tags_add — equivalente a tags. Adiciona sem remover

  • tags_remove — lista separada por vírgulas. Remove tags específicas

Se o mesmo contato aparece em tags_add e tags_remove na mesma importação, a remoção ganha (ordem: primeiro adiciona, depois remove).

Para remoção em massa por outro caminho, use a API de remoção de tags.

Telefones brasileiros

Sempre inclua o código do país (+55) e o 9 no início do celular.

  • Sem +55 → duplicidade

  • Sem o 9 → duplicidade + impacto em campanhas WhatsApp

Exemplo correto: +5511960832431 (+55 é o código de país; o 9 foi adicionado pela Anatel há alguns anos).

Normalização automática

Nota técnica: o sistema possui normalização automática — se você enviar +551160832431 (sem o 9), o sistema adiciona automaticamente. Mas recomendamos fortemente incluir o 9 no CSV para evitar ambiguidade.

Lookup de variantes (BR mobile-9)

Ao identificar contatos existentes, o sistema busca variantes do telefone enviado. Se o CSV envia +5511933334444 e o contato existe como +551133334444 (sem o 9), o match acontece e o contato é atualizado em vez de duplicado.

Caracteres não-imprimíveis

Caracteres null-byte (\x00) em qualquer célula são silenciosamente removidos durante a importação.

Bloqueando contatos via CSV

A coluna blocked é aceita e bloqueia o contato no momento da importação.

Operação Valores aceitos (case-insensitive)
Bloquear true, 1, yes, t, on
Desbloquear (se já estava bloqueado) false, 0, no, f, off
Vazio Contatos novos: desbloqueado por padrão. Contatos existentes: estado atual preservado

Mudança a partir de 30/04/2026: contas que enviavam CSVs com blocked antes dessa data tinham essa coluna silenciosamente ignorada. Agora o valor é respeitado. Para aplicar valores históricos retroativamente, basta re-importar o CSV.

Apagando dados via CSV

Para apagar um campo de um contato existente, use o valor especial __DELETE__ na célula:

  • Em phone_number, email, identifier, name → o campo é limpo (NULL)

  • Em colunas de atributos personalizados → a chave é removida do JSON do contato

  • Não funciona em blocked — para desbloquear, use false (ou 0/no/f/off)

Se você usa literalmente a string "__DELETE__" como valor legítimo em algum campo, acione o suporte antes da importação para evitar perda de dados.

Atenção: dual-write em company, company_name e city

Valores nas colunas company, company_name e city são gravados simultaneamente em additional_attributes e em custom_attributes do contato. Isso garante que dashboards, filtros e segmentações encontrem o valor.

Mudança a partir de 30/04/2026: antes apenas additional_attributes era populado, o que causava inconsistência em filtros baseados em atributos personalizados.

O que acontece na prática

Ao importar:

  1. Sistema busca se o contato já existe — pelo email, identifier e telefone, nessa ordem de prioridade

  2. Se não encontrar → cria um contato novo

  3. Se encontrar → atualiza informações conforme as regras de campos em branco

Divergência de identificadores (AMBIGUOUS_MATCH) — se o CSV contiver um contato com dois ou mais campos chave (email, telefone, identifier) que apontem para contatos diferentes já existentes, a linha é rejeitada com erro AMBIGUOUS_MATCH.

Exemplo: se o email [email protected] pertence ao contato A, mas o telefone +5511960832431 pertence ao contato B, o sistema não saberá qual atualizar e rejeita a linha.

Mudança a partir de 30/04/2026: antes, o sistema usava o primeiro match encontrado e silenciosamente sobrescrevia dados. Agora a linha é rejeitada explicitamente. Corrija manualmente antes de reimportar.

Linhas duplicadas no CSV

Se o CSV tiver duas ou mais linhas com o mesmo email, telefone ou identifier, apenas a primeira é processada — as demais são rejeitadas como duplicatas. Vale mesmo se as outras informações forem diferentes.

Dica: revise o CSV antes de importar.

Adicionar mais informações (tags e campos customizados)

Você pode editar qualquer informação adicionando a chave do campo como título de uma nova coluna.

Adicionar tags

Crie uma coluna tags e preencha cada célula com a tag desejada.

A tag precisa já existir. Se não existir, sua importação falhará.

Crie tags em Configurações → Tags ou diretamente na aba de contatos:

Adicionar atributos personalizados

Pegue a chave do atributo customizado em Configurações → Atributos Personalizados e use como nome da coluna no CSV.

Campos do perfil que não entram por CSV

Alguns campos que existem no cadastro do contato não têm coluna padrão no import. Criar uma coluna com o mesmo nome não preenche o campo do perfil: ela vira um campo personalizado com aquele nome, e o campo nativo continua vazio.

Campo do perfil Tem coluna no CSV? Como preencher
Descrição Não Tela do contato, ou API de contato individual (additional_attributes.description)
País / código do país Não Tela do contato, ou API (additional_attributes.country e country_code)
Perfis de redes sociais (Twitter/X, Facebook, LinkedIn, GitHub, Instagram) Não Só pela tela do contato ou pela API de contato individual. Os caminhos em massa — CSV e API de importação em lote — ignoram esse campo por segurança
Foto (avatar) Não Tela do contato, ou avatar_url na API

Para preencher esses campos em escala, use a API de contatos: Como criar, atualizar e deletar contatos via API.

Ao atualizar por API, o bloco additional_attributes é substituído inteiro pelo que você enviar (diferente de custom_attributes, que é mesclado). Mande sempre o conjunto completo — descrição, empresa, cidade, país, redes sociais — para não apagar o que já estava lá.

Se o dado só precisa ficar registrado e disponível para filtro, segmentação e relatório (e não no campo nativo), o caminho por CSV é criar um campo personalizado: inclua a coluna e escolha Criar novo campo personalizado na etapa de revisão.

Mais de um e-mail ou telefone no mesmo contato

Um contato no Cloud Chat tem um e-mail, um telefone e um identificador. Os três são chaves de identidade e cada valor é único dentro da conta — não existe campo nativo de "e-mail secundário" ou "telefone 2". Dois e-mails na mesma célula são lidos como um único e-mail (inválido).

Objetivo Caminho
Guardar o dado extra no cadastro e usá-lo em filtro, segmentação e relatório Crie campos personalizados — por exemplo email_secundario, telefone_2 — e importe como colunas normais do CSV
Juntar dois cadastros que são a mesma pessoa Mesclar contatos: as conversas dos dois passam a viver no contato que sobra
Falar com a pessoa no segundo número ou e-mail Precisa ser um contato separado — campanhas e disparos usam o email e o phone_number do cadastro

Na mesclagem, o cadastro que fica manda: nome, e-mail, telefone e identificador do contato secundário só são aproveitados quando o campo correspondente do principal estiver vazio. O segundo e-mail não é preservado como e-mail adicional — se você precisa dele, guarde num campo personalizado antes de mesclar.

Detalhes em Como mesclar (merge) contatos via API e Como mesclar conversas de um mesmo contato.

Subir o import no Cloud Chat

Salve a planilha como CSV (UTF-8), volte à seção de importação, escolha o arquivo e clique em Importar.

Revisar as colunas

Se o arquivo tiver pelo menos uma coluna que o Cloud Chat não reconhece, aparece uma etapa de revisão antes de importar. Se todas as colunas forem reconhecidas, o import começa direto.

Nessa etapa você decide, coluna por coluna:

Ação O que acontece
Ignorar A coluna não é importada. Nada é criado a partir dela.
Criar novo campo personalizado Cria um campo personalizado de contato (tipo texto) com o nome da coluna. Se já existir um com a mesma chave, ele é reaproveitado.
Mapear numa coluna existente Manda o conteúdo para um campo padrão (name, email, phone_number, company_name, city, tags) ou para um campo personalizado que a conta já tem.

As sugestões já vêm preenchidas: coluna desconhecida vem como Criar novo campo personalizado; coluna descontinuada vem como Ignorar, com um alerta na tela. Duas colunas não podem ser mapeadas para o mesmo destino.

Campos descontinuados: id, ip_address e identifier aparecem marcados como descontinuados e já vêm com a sugestão de ignorar. Não use a coluna id da sua ferramenta antiga como identificador de contato aqui — o identifier continua sendo aceito como chave de identidade, mas não é mais sugerido para bases novas.

Antes dessa etapa, qualquer coluna não reconhecida virava campo personalizado sem aviso. É daí que vêm campos como id ou ip_address no cadastro de contato de contas antigas — dá pra apagá-los em Configurações → Atributos Personalizados.

Quando o sistema concluir (pode levar até 30 minutos), você recebe um e-mail com o número de sucessos e falhas.

IMPORTANTE: garanta que o CSV está no encoding UTF-8. Outros encodings podem gerar caracteres inválidos ou impedir o match de tags.

Observações