Principal Primeiros passos do administrador Como importar contatos em massa via CSV

Como importar contatos em massa via CSV

Última atualização em May 21, 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

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:

Detalhes importantes sobre o CSV

São colunas padrões — você pode adicionar mais colunas (tags, campos personalizados). 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.

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.

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