Como importar contatos em massa via CSV
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
:::info 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.
:::warning 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.
:::
:::info 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.
:::warning Os campos que determinam um contato único são telefone, e-mail e identificador (identifier). Pelo menos um
precisa estar sempre presente.
:::
:::info 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
:::info 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
:::warning 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
:::info 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 |
:::warning 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)
:::warning 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
:::warning 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
:::error 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
:::warning 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.
:::warning 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 |
:::info 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 |
:::warning 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.
:::warning 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.
:::
:::info 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.
:::
:::success Quando o sistema concluir (pode levar até 30 minutos), você recebe um e-mail com o número de sucessos e
falhas.
:::
:::error 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
- Para volumes via API: Como importar contatos em massa via API
- Para importar via HubSpot: Como importar contatos via HubSpot
- Para criar atributos personalizados antes de usar no CSV: Como criar campos customizados de contatos e conversas
- Para preencher descrição, país ou redes sociais em escala: Como criar, atualizar e deletar contatos via API
- Para remover tags em massa via API: Como remover tags de contatos em massa via API
