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 árabe do Windows; vírgulas, ponto e vírgula ou tabulações) ou Excel .xlsx (a primeira planilha). Até 20 MB e 100.000 linhas. Um Excel antigo .xls é recusado: no Excel, escolha Arquivo > Salvar como > Pasta de Trabalho do 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. Nós deduzimos a partir dos cabeçalhos em inglês e em árabe (الجوال → Telefone (WhatsApp), الاسم → Nome, um cabeçalho que corresponde a um campo personalizado → esse campo). Defina as colunas de que você não precisa como Não importar. Exemplo mostra um valor do arquivo. 4. Em Opções: - País dos números locais: números escritos sem código do país (0501234567, ou 501234567 quando o Excel removeu o zero) são lidos como números deste país. Dígitos arábicos orientais (٠٥٠...) funcionam. Uma coluna País no arquivo prevalece para a linha dela. Começa com o país da sua empresa. - 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). 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 que concordaram (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. 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). 10. Quando você vir Importação concluída., clique em Ver contatos importados para ver a lista, ou em Baixar errors.csv. Abaixo dos totais, Todos que esta importação criou ou atualizou estão na lista "Import – customers.csv – 2026-09-24" (n pessoas). indica a lista que a importação criou; Abrir a lista a abre em Contatos → Públicos (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 workspace 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 workspace 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 workspace, 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 dar nome às colunas → adicione uma linha de cabeçalho.
• O arquivo tem mais de 100.000 linhas ou O arquivo tem mais de 20 MB → divida-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 no errors.csv, com o motivo: Não é um número de telefone válido (confira o código do país) (confira 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 é indicado no detalhe: uma opção deve ser uma das opções dele, uma data AAAA-MM-DD ou dia/mês/ano, um número apenas dígitos), A coluna de consentimento deve dizer sim ou não, Já é um contato - ignorado, Não foi possível salvar (tente importar essa linha de novo). O errors.csv tem as próprias colunas do arquivo, então você pode corrigir as linhas e importá-las como um novo arquivo.
• 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 e pelo menos um entre Telefone (WhatsApp) (com o código do país, ou um número local do País que você escolher), E-mail ou Usuário em outra plataforma com a Plataforma dele.
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. Clique em Adicionar contato. Você vê {name} foi adicionado. e o contato se abre.
5. Esta pessoa já está em Contatos. → o número ou e-mail pertence a alguém; clique em Abrir o contato.

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 (name, phone, email, handle + platform, country, tags, notes, attributes, consent: {channels, evidence}); 409 retorna o contactId existente. Importações: POST .../contacts/imports (multipart file), GET .../contacts/imports/{id}, PATCH {mapping, options}, POST .../validate, POST .../run, POST .../cancel, GET .../errors.csv?lang=ar. O GET de uma importação concluída retorna audience (id, name, memberCount) — a lista acima.

Relacionado

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