Importar contatos do Excel ou CSV (com consentimento)

Contatos → Importar (/app/contacts/import) traz uma lista inteira de clientes de um arquivo. Adicionar contato na página Contatos adiciona uma pessoa manualmente. Nada é salvo até você verificar o arquivo e clicar no botão de importar.

Antes de começar

• Importar exige a tarefa Importar contatos (Proprietários e Administradores por padrão; um Proprietário ou Administrador pode dá-la a qualquer pessoa com Editar acesso em Configurações → Membros, veja Funções e tarefas). Sem ela, o botão Importar fica oculto e a página diz Importar contatos exige a tarefa Importar contatos. Peça a um Proprietário ou Admin.
• Adicionar contato exige a tarefa Gerenciar contatos (Proprietários, Administradores e Editores por padrão).
• O arquivo: CSV (UTF-8, UTF-16 ou Windows Arabic; vírgulas, ponto e vírgula ou tabs) ou Excel .xlsx (a primeira planilha). Até 20 MB, 100.000 linhas e 200 colunas. Um .xls antigo do Excel é recusado: no Excel escolha Arquivo > Salvar Como > Livro de Exercícios Excel (.xlsx) ou CSV UTF-8.
• A primeira linha deve dar nome às colunas, por exemplo Name, Phone, Email ou الاسم، الجوال، البريد الإلكتروني. Cada pessoa precisa de um número de telefone ou de um e-mail.
• Para importar dados personalizados (nível de associação, aniversário...), crie antes os campos em Campos personalizados de contato.

Passo a passo: importar um arquivo

1. Em Contatos, clique em Importar.
2. Arquivo: clique em Escolher um arquivo, selecione-o e clique em Enviar. Você vê Lendo o arquivo… e depois as colunas.
3. Colunas: em Associar as colunas cada coluna do seu arquivo tem uma caixa Importar como . A partir dos cabeçalhos nos dez idiomas do app, com ou sem sotaques ('الجوال', 'Téléphone', 'Handy' ou 'Cep telefonu' → Telefone (WhatsApp), 'الاسم', 'Nom complet' ou 'Nama' → Nome, um cabeçalho que corresponde a um campo personalizado → esse campo). Ao lado de uma coluna de primeiro nome, um 'Nom' ou 'Name' simples é considerado como sobrenome; ao lado de uma coluna de sobrenome, 'Nome' ou 'Nombre' é o primeiro nome. Defina colunas que você não precisa Não importar. Exemplo mostra um valor do arquivo. Quando uma coluna definida como Não importar parece números de telefone ou endereços de e-mail (e nenhuma outra coluna está definida para eles), uma linha amarela abaixo dela diz isso, por exemplo . Esta coluna parece números de telefone, mas está configurada para "Não importar", então eles não serão importados. Escolha "Telefone (WhatsApp)" para importá-los.
4. Em Opções:

• País dos números locais: números escritos sem código de país ('07400 123456', ou '7400 123456' quando o Excel eliminou o zero) são lidos como números deste país. Dígitos árabes (٠٥٠...) são válidos. Uma coluna País no arquivo vence para sua linha. Ela começa como o país da sua empresa (sem nenhum padrão, ela lê Escolha um país, e apenas números escritos com seu código de país são lidos); a lista tem todos os países, nomeados no seu idioma, em ordem alfabética em Todos os países (o país que seu navegador diz que você está, quando diz, vem primeiro em Sugerido).
• Pessoas que já estão em Contatos (mesmo telefone ou e-mail): Atualizá-las com os valores do arquivo (células preenchidas substituem o que o contato tinha, células vazias nunca apagam nada, tags são adicionadas, um telefone ou e-mail só é adicionado quando o contato não tem nenhum) ou Ignorá-las.
• Tags extras para todos os importados (separadas por vírgulas): até 10 tags, cada uma com até 50 caracteres (um # no início é ignorado). Mais que isso mostra Add at most 10 extra tags. Remove some, or add them later with Add tags. abaixo da caixa, e uma tag mais longa A tag can be at most 50 characters. Shorten it, or split it with a comma.; Continuar espera até a caixa estar correta.

5. Clique em Continuar.
6. Consentimento: escolha Não - não concordaram, ou não sei ou Sim - concordaram, e sei dizer como. Para sim, marque os Canais com consentimento (WhatsApp, SMS, E-mail), escolha Onde concordaram?, escreva Como essas pessoas concordaram? (pelo menos 10 caracteres, por exemplo "Marcaram Quero receber ofertas no WhatsApp ao entrar no nosso programa de fidelidade"), preencha Quando concordaram (opcional) se souber e marque Confirmo que essas pessoas deram este consentimento e posso apresentar prova se solicitado.
7. Clique em Verificar o arquivo. A verificação lê todas as linhas e não salva nada (Verificando n de N linhas…).
8. Resultado da verificação mostra Prontos para importar, Com problemas, Contatos novos, Já em Contatos e Repetidos no arquivo, e as Primeiras linhas com problemas com o motivo. Alterar configurações leva você de volta; Baixar errors.csv traz todas as linhas com problema. Um contato tem no máximo 20 tags: quando algumas pessoas passariam disso, a verificação diz, por exemplo, 3 contacts would pass the limit of 20 tags. They keep their tags and get this import's own tag; the other new tags are added only while there is room. Um arquivo feito com Exportar CSV é importado como está: o apóstrofo na frente de um número como '+447400123456 é retirado.
9. Clique em Importar n contatos. Importando n de N… mostra o progresso. Você pode sair da página: a importação continua, e Contatos → Importar → Importações recentes a reabre (Abrir). Um arquivo enviado que você deixou antes de importar (em Colunas, Consentimento ou depois de Verificar o arquivo) aparece em Importações recentes como Não concluída, com Continuar (volta para onde você parou) e Descartar. Descartar pergunta "Descartar o arquivo enviado "(arquivo)"? Nada dele foi importado. As linhas e o arquivo guardado serão excluídos." e o remove da lista. Arquivos enviados que ficam sem concluir por 7 dias são descartados automaticamente; em nenhum caso nada muda em Contatos.
10. Quando vir Importação concluída. pressione Ver contatos importados para ver a lista, ou Baixar errors.csv (mostrado, com As linhas que não foram importadas, com o motivo, nas colunas originais do arquivo., apenas quando algumas linhas não foram importadas). Sob os totais, Todos que essa importação criou ou atualizou estão na lista "Importar – customers.csv – 2026-09-24" (n pessoas). Nomeie a lista que a importação fez; Abrir a lista e a abra em Contatos → Audiências (veja a próxima seção).

A lista da importação

Quando uma importação termina, todos que ela criou ou atualizou são colocados em uma nova lista (um público estático) chamada Import – <file name> – <date> (nome do arquivo e data), por exemplo Import – customers.csv – 2026-09-24. Use-a como qualquer lista: escolha-a como público de uma transmissão do WhatsApp, abra-a em Contatos → Públicos, adicione ou remova pessoas (Públicos).

• Pessoas ignoradas (já em Contatos, com Ignorá-las), linhas com problemas e linhas que não puderam ser salvas não estão nela.
• A data é o dia em que a importação terminou. Importe o mesmo arquivo de novo no mesmo dia e as pessoas dele entram na mesma lista; em outro dia, você recebe uma lista nova.
• Uma importação cancelada não recebe lista. As pessoas que ela já tinha importado mantêm a tag da importação, então você ainda pode encontrá-las.
• Um espaço de trabalho mantém até 500 públicos. Quando ele já tem 500, a importação termina sem lista e diz Nenhuma lista foi criada para esta importação: o espaço de trabalho já mantém 500 públicos. Arquive as listas de que você não precisa mais em Contatos → Públicos; a tag continua marcando todos do arquivo.

Como as pessoas são associadas (sem duplicatas)

• Uma linha é a mesma pessoa que um contato quando o número de telefone dela (depois de escrito como +código do país e número) ou o e-mail já está neste espaço de trabalho, em qualquer canal. Um contato unificado é atualizado como uma só pessoa.
• Duas linhas com o mesmo número ou e-mail em um arquivo viram um só contato: a primeira o cria, as seguintes o atualizam (ou são ignoradas quando você escolheu Ignorá-las).
• Um contato novo com número de telefone é criado como o contato de WhatsApp dessa pessoa, então quando ela escrever para você as mensagens chegam ao mesmo cartão. A Origem dele é Importação.
• Cada contato importado recebe a tag própria da importação, import: mais a data e o nome do arquivo (por exemplo import:2026-09-24-customers-3f9a), para que você os encontre de novo na página Contatos (filtrando pela tag), além da lista da importação acima.

Consentimento: o que é registrado

• Com Sim, cada pessoa recebe um registro de consentimento por canal marcado, com a origem Importação e a sua declaração, o local, a data e o nome do arquivo como evidência, além de quem iniciou a importação. Ele aparece em Histórico de consentimento no contato (Consentimento e descadastro).
• Só para canais em que a linha tem um endereço: WhatsApp e SMS precisam de número de telefone, e-mail precisa de e-mail.
• Uma coluna Consentimento de marketing (sim / não) no arquivo: só as linhas que dizem sim (yes, y, 1, نعم, موافق) recebem consentimento; linhas que dizem não ou estão vazias não recebem. Uma coluna assim exige a declaração (Sim) ou deve ser definida como Não importar.
• Pessoas que retiraram o consentimento ou responderam STOP mantêm a escolha (contadas como Mantido o "não" anterior). Uma importação nunca a substitui; só a própria pessoa, ou um colega que registre a nova aceitação dela com Registrar consentimento, pode.
• Com Não, ninguém recebe consentimento de marketing. As pessoas ainda podem receber respostas dentro da janela de 24 horas e mensagens de utilidade.

Se algo der errado

• Este é um arquivo antigo do Excel (.xls)... → salve-o como .xlsx ou CSV UTF-8 e envie de novo.
• A primeira linha deve nomear as colunas → adicionar uma linha de cabeçalho. O arquivo tem nomes de colunas, mas não linhas de pessoas. → o arquivo tem uma linha de cabeçalho e nada abaixo dela (ou apenas linhas vazias); adicione uma linha por pessoa sob os nomes das colunas e faça o upload novamente. O arquivo está vazio. significa que nada foi encontrado no arquivo.
• O arquivo tem mais de 100.000 linhas ou O arquivo é maior que 20 MB → dividi-lo. A segunda mensagem também aparece para um arquivo pequeno, mas que contém milhões de células preenchidas uma vez aberto.
• O arquivo tem mais de 200 colunas. → delete as colunas que você não precisa. Um valor digitado muito à direita, mesmo em uma coluna vazia, conta; células vazias não.
• Mapeie uma coluna de telefone ou de e-mail. → defina uma coluna como Telefone (WhatsApp) ou E-mail.
• Duas colunas estão definidas como "…" → defina uma delas como Não importar.
• Linhas em errors.csv, com o motivo: Não é um número de telefone válido (confira o código do país) (verifique País dos números locais), Sem número de telefone ou e-mail, Não é um endereço de e-mail válido, País desconhecido, Idioma desconhecido, Fuso horário desconhecido, Um valor de campo personalizado não se encaixa no campo (o campo é nomeado em detalhes: uma escolha deve ser uma de suas opções, uma data YYYY-MM-DD ou dia/mês/ano, apenas dígitos numéricos), A coluna de consentimento deve dizer sim ou não, Já é um contato - ignorado, Não foi possível salvar (tente importar essa linha novamente). errors.csv tem as próprias colunas do arquivo, então você pode corrigir as linhas e importá-las como um novo arquivo. Ele vem no idioma em que você usa o app: suas quatro primeiras colunas (linha, status, motivo, detalhe), o status de cada linha e o motivo estão nesse idioma.
• Cancelar importação para antes das próximas 1.000 linhas; os contatos já importados permanecem.
• As linhas e a cópia armazenada do arquivo são excluídas 30 dias após o envio; depois disso o errors.csv não fica mais disponível (As linhas deste arquivo foram excluídas 30 dias após o envio.). Os totais da importação e a declaração de consentimento são mantidos.

Adicionar um contato

1. Em Contatos, clique em Adicionar contato.
2. Preencha Nome (até 120 caracteres) e pelo menos um de Telefone (WhatsApp) (com o código do país, ou um número local do País escolhido), E-mail ou Usuário em outra plataforma com sua Plataforma. País começa como o país da sua empresa (Configurações → Empresa) e lista todos os países nomeados no seu idioma; sem nenhum definido, ele diz Escolha um país. Os dígitos digitados em um teclado árabe (٠٥٥...) passam a ser 0-9 em Telefone (WhatsApp) conforme você digita, então o número se leia da esquerda para a direita em sua ordem usual.
3. Opcional: Tags (separadas por vírgulas), Notas e, em Consentimento de marketing (opcional), os canais com que a pessoa concordou, mais Como a pessoa concordou?
4. Pressione Adicionar contato. Você vê [nome] foi adicionado. e o contato se abre.
5. Esta pessoa já está em Contatos. → o número ou e-mail pertence a alguém; pressione Abrir o contato. Quando uma caixa é o problema, o motivo aparece em vermelho sob essa caixa, a caixa fica vermelha e o cursor se move para dentro dela. Por exemplo Esse não é um número de telefone válido para o país escolhido. Insira um número local daquele país, ou o número completo começando com + e o código do país. em Telefone (WhatsApp) (sem País escolhido: Esse não é um número de telefone válido. Verifique os dígitos depois do + e do código do país, ou escolha o País abaixo e insira um número local.), Escolha a plataforma do usuário. em Plataforma (sempre que um endereço for digitado, mesmo com telefone ou e-mail), O consentimento do WhatsApp ou SMS precisa de um número de telefone. Digite o número ou desmarque o WhatsApp e o SMS. em Telefone (WhatsApp) O consentimento de e-mail exige um endereço de e-mail. Insira o endereço ou desmarque E-mail. ou Digite um endereço de e-mail como nome@exemplo.com. em E-mail, ou Diga como a pessoa concordou (pelo menos 3 caracteres). em Como a pessoa concordou? Cada motivo está no seu idioma. Corrija e pressione Adicionar contato novamente. Uma mensagem sobre o formulário como um todo (Informe um número de telefone, um e-mail ou um usuário. aparece no final.

Um contato adicionado só por usuário ganha o próprio cartão; quando a pessoa escrever para você por essa plataforma, unifique os dois com Unificar com… (Contatos).

Desenvolvedores (API)

'POST /workspaces/{workspaceId}/contacts' adiciona um contato ('nome', 'telefone', 'email', 'handle' + 'plataforma', 'país', 'tags', 'notes', 'atributos', 'consent: {channels, evidence}'); 409 retorna o 'contactId' existente. Importações: 'POST .../contacts/imports' (multiparte 'arquivo'), 'GET .../contacts/imports/{id}', 'PATCH' '{mapping, options}', 'POST .../validate', 'POST .../run', 'POST .../cancel', 'GET .../errors.csv?lang=ar' ('lang': en, ar, fr, es, pt, de, tr, id, hi ou your). O 'GET' de uma importação finalizada retorna 'público' ('id', 'name', 'memberCount') — a lista acima.

Relacionado

• Contatos
• Listas e segmentos (públicos)
• Consentimento e descadastro
• Campos personalizados de contato
• Transmissões do WhatsApp