Preparar o arquivo CSV de contatos

O CSV é a lista de quem vai receber a campanha. A maior parte das campanhas que falham, falha aqui — vale conferir o arquivo antes de subir.

O formato mínimo

O arquivo precisa ter uma primeira linha de cabeçalho com os nomes das colunas, e as colunas obrigatórias são nome e telefone:

nome,telefone
Maria Silva,11987654321
João Souza,11912345678

Os nomes das colunas não são sensíveis a maiúsculas: Nome, NOME e nome são lidos igual. Espaços em volta do nome da coluna também são ignorados.

Regras do arquivo

Atenção: ao exportar do Excel em português, o separador costuma sair como ponto e vírgula. Isso é aceito — o que não pode é misturar separadores diferentes no mesmo arquivo.

A codificação é UTF-8

O sistema não converte codificação. Um arquivo salvo em ANSI ou Windows-1252 — que é o formato que o Excel oferece por padrão em português — faz os acentos chegarem corrompidos, e o cliente recebe a mensagem com o nome errado.

No Excel, use Salvar como → CSV UTF-8. Se o seu Excel não oferecer essa opção, abra o arquivo no Bloco de Notas e salve escolhendo a codificação UTF-8.

O sistema lida bem com a marca invisível que o Excel coloca no início do arquivo ao salvar em UTF-8, então isso não é problema.

Como o telefone é tratado

O telefone é o campo mais sensível do arquivo, mas o sistema é mais tolerante do que parece. Antes de validar, ele:

1. Remove tudo que não é número. Parênteses, espaços, hífens e pontos são descartados.
2. Remove o zero inicial, se houver.
3. Acrescenta o 55 quando o número não começa com ele.

Todos estes formatos chegam ao mesmo número e funcionam:

11987654321
5511987654321
(11) 98765-4321
11 98765-4321
011 98765-4321
+55 11 98765-4321

O que o sistema aceita, no fim das contas:

O que não funciona:

• Número sem DDD.
• Campo de telefone vazio — a linha é ignorada e não entra no resultado.
• Qualquer outra quantidade de dígitos.

Nota: contra o que se costuma supor, escrever o DDD com zero na frente (011) não quebra o arquivo — o zero é removido automaticamente. O que quebra é a falta do DDD.

Linhas com telefone inválido entram no resultado da campanha como falha, com o número original preservado e a mensagem "Telefone inválido ou não encontrado no contato/lead.", para você conseguir corrigir a base.

Colunas opcionais

Colunas de personalização

Qualquer coluna a mais pode alimentar uma variável do template. Se o seu template diz "Olá {{nome}}, o {{modelo}} que você viu chegou", inclua uma coluna modelo:

nome,telefone,modelo
Maria Silva,11987654321,Onix 2024
João Souza,11912345678,Tracker 2025

Na criação da campanha, você associa cada variável do template à coluna correspondente.

Coluna leadid

Se a sua base vem do CRM, inclua uma coluna leadid com o identificador do lead. O identificador fica registrado junto ao contato da campanha, servindo de referência para cruzar o resultado com o CRM depois.

nome,telefone,leadid
Maria Silva,11987654321,48219

Nota: a coluna leadid não vincula automaticamente a conversa ao lead do CRM. Ela guarda o identificador. A vinculação continua sendo feita no atendimento. Ver Vincular um lead ao atendimento.

Checklist antes de subir

1. A primeira linha é o cabeçalho, com nome e telefone.
2. O arquivo está salvo em UTF-8.
3. O separador é o mesmo no arquivo inteiro.
4. Nenhum campo passa de 100 caracteres.
5. Não há linhas com telefone em branco.
6. Todos os números têm DDD.
7. Não há telefones repetidos.
8. A coluna de nome está preenchida em todas as linhas.
9. As colunas das variáveis do template existem e estão preenchidas.
10. O arquivo tem menos de 100 MB.

Contatos que não vão receber

Mesmo com o arquivo correto, alguns contatos não recebem a mensagem:

• Quem fez opt-out. O sistema confere a lista de descadastro no momento do processamento e bloqueia o envio, registrando a linha como falha. Ver Como funciona o opt-out.
• Números sem WhatsApp, nas contas em que a validação de número está habilitada (nome interno: must_validate_whatsapp_number).

Perguntas frequentes

Posso usar Excel? Sim, para montar. Na hora de salvar, use Salvar como → CSV UTF-8.

O arquivo foi recusado como "tipo inválido", mas é um CSV. A validação aceita apenas arquivos identificados como CSV. Dependendo de como a planilha foi salva, o Windows pode marcar o arquivo como documento do Excel mesmo com a extensão .csv. Salve novamente pela opção CSV UTF-8, sem renomear a extensão manualmente.

O nome é obrigatório? O telefone é o que define se a linha entra. Sem nome preenchido, o próprio número de telefone é usado no lugar do nome — e, se o template usa a variável de nome, o cliente recebe "Olá 11987654321". Preencha a coluna.

Acentos e cedilha funcionam? Sim, desde que o arquivo esteja em UTF-8. Em outra codificação os acentos chegam corrompidos.

Posso repetir o mesmo telefone? Não faça isso. Não existe remoção de duplicados: cada linha gera um envio, então um telefone repetido três vezes recebe a mesma mensagem três vezes. Remova as duplicatas na planilha antes de subir.

Quantos contatos cabem? O limite prático é o tamanho do arquivo: 100 MB.

Artigos relacionados

• Criar uma campanha
• Erros comuns em campanhas
• Preencher as variáveis do template
• Como funciona o opt-out