# Como importar sua base de clientes para o WhatsApp

> Como trazer a base da loja para o WhatsApp (Shopify, VTEX ou planilha CSV) e separar quem pode receber mensagem: opt-in, opt-out e segmentos.

- Fonte: https://www.ztgrowth.com.br/guia/importar-base-de-clientes-whatsapp/
- Formato: Guias
- Publicado em: 2026-11-16
- Atualizado em: 2026-11-16

**Resposta curta:** a base da loja chega ao WhatsApp por três caminhos: a integração com a plataforma (Shopify, VTEX ou Wake), que traz clientes e pedidos; o import histórico, que traz os pedidos antigos; e a planilha CSV, para o que está fora da loja. Importar não é o mesmo que poder mandar. Antes do primeiro disparo, separe quem deu [opt-in](https://www.ztgrowth.com.br/glossario/opt-in/) para receber mensagens da marca no WhatsApp, e respeite quem pediu para sair. Na ztgrowth, quem pediu para sair fica registrado no cliente, e nenhuma importação muda isso.

## Ter o telefone não é poder mandar

A Meta exige que o cliente tenha aceitado receber mensagens da marca no WhatsApp. Na prática, opt-in claro no checkout, no cadastro ou no próprio chat, dizendo o que a pessoa vai receber. Ter o número no cadastro não é consentimento.

Por isso, a importação tem duas perguntas diferentes:

- **Quem é o cliente?** Telefone, nome, o que comprou e quando. É o que deixa o agente e as jornadas falarem com contexto.
- **Quem pode receber mensagem ativa?** Quem deu opt-in e não pediu para sair. É o que protege a qualidade do número.

Uma base grande e bem importada, mandada para quem não aceitou, vira denúncia. E denúncia derruba a qualidade do número, que é o que impede o limite de mensagens de subir.

## Os três caminhos

| Caminho | O que traz | Quando usar |
| --- | --- | --- |
| Integração com a plataforma | Clientes, pedidos, status e entregas, daqui para frente | Sempre. É a fonte principal da base. |
| Import histórico | Pedidos antigos, com a data de cada um | No onboarding, para as jornadas de recompra e winback partirem do histórico real. |
| Planilha CSV | Contatos e campos que a loja tem fora da plataforma | Lista de evento, loja física, cadastro antigo, dados de outro sistema. |

### 1. A integração com a plataforma

Na [Shopify](https://www.ztgrowth.com.br/integracoes/shopify/), a integração é um app: a marca aprova as permissões, e a ztgrowth registra os webhooks de pedido e cliente na loja. Na [VTEX](https://www.ztgrowth.com.br/integracoes/vtex/), ela usa uma App Key e um App Token da conta, e cada mudança de status do pedido chega pelo Order Hook. Em ambas, o comprador do pedido é ligado ao contato do WhatsApp, e o histórico de compra passa a fazer parte da memória do agente.

A integração é o caminho que mantém a base viva: todo pedido novo atualiza o cliente, sem planilha.

### 2. O import histórico

A integração começa no dia da conexão. O que veio antes precisa de import. Na Shopify, a base histórica de clientes e pedidos é importada no onboarding. Cada pedido com telefone vira (ou completa) um cliente, com a data do próprio pedido.

Duas regras do import histórico:

- **Ele não fala com ninguém.** Um pedido de meses atrás entra só como registro: não manda "obrigado pela compra", não dispara recuperação de carrinho, não gera cupom.
- **Pedido sem telefone conta na receita, mas não vira contato.** Sem número, não há com quem conversar.

Se a loja trocou de plataforma, os pedidos da loja antiga não precisam ficar para trás. Quem saiu da VTEX para outra plataforma pode trazer os pedidos da loja VTEX antiga, com a credencial guardada só para aquele import e apagada no fim. A squad roda esse import. Na VTEX, o telefone que vem mascarado no pedido conta como pedido sem telefone.

### 3. A planilha CSV

Para o que não está na plataforma, o portal importa uma planilha em Clientes, Importar. As regras:

- **Só .csv, com cabeçalho, até 200.000 contatos por arquivo.**
- **A coluna de WhatsApp é obrigatória.** É ela que identifica o cliente. Linha com WhatsApp inválido ou vazio é pulada e aparece no relatório do import.
- **O número é normalizado.** Pontos, traços e espaços saem. Um celular brasileiro com DDD e sem o 55 (11 dígitos começando pelo 9 depois do DDD) ganha o 55. Um número com 55 e sem o nono dígito ganha o 9.
- **Toda importação entra em pelo menos uma lista.** Escolha uma lista existente ou crie uma nova. É a lista que depois vira público de campanha ou gatilho de jornada.

## Passo a passo do import por planilha

### 1. Limpe a planilha antes

Uma linha por pessoa. Telefone com DDD. Tire número de fornecedor, de funcionário e de teste. Se a planilha veio de outra ferramenta, separe quem pediu lá para não receber mais mensagens: esse pedido continua valendo. Como a planilha não altera o opt-out, essas pessoas ficam fora do arquivo de campanha, ou o opt-out delas é marcado à parte.

### 2. Escolha as listas

Todos os contatos do arquivo entram nas listas escolhidas. Uma lista com nome claro ("Feira de outubro", "Loja física Centro") facilita o recorte depois.

### 3. Relacione as colunas

Cada coluna vira um campo do cliente, salvo como propriedade da Memória. Prefira uma chave que já existe, para não ter "cidade" e "Cidade" como dois campos. Ao criar uma propriedade nova, escolha o tipo:

- **Texto**, para o que não é conta nem data.
- **Número**, que aceita 35,50 ou 35.50 e serve para condições de maior ou menor e para o valor de um cupom.
- **Data / timestamp**, que aceita 30/10/2026, 30/10/2026 14:22 ou 2026-10-30. Guarda só o dia, e data com barra é sempre lida como dia/mês/ano.

O tipo fica fixo depois de criado. Também dá para aplicar um valor fixo a todos os contatos do arquivo, como a origem da lista.

### 4. Revise e decida se o import inicia fluxos

Na revisão, duas regras ficam à vista: célula em branco não sobrescreve dado que já existe, e o opt-out nunca é alterado pela planilha.

Se uma das listas tem uma jornada publicada esperando quem entra nela, o import pode iniciar essa jornada para os contatos importados. O número final pode ser menor que o do arquivo: quem deu opt-out, quem está na janela de reentrada da jornada e, conforme o gatilho, quem já estava na lista ficam de fora. Se a ideia é só guardar a base, importe sem iniciar fluxos.

### 5. Leia o relatório

O relatório mostra quantos contatos foram criados, quantos foram atualizados e uma amostra das linhas com problema: WhatsApp inválido ou data ilegível. Com data ilegível, a pessoa entra sem aquele campo. Corrija as linhas no arquivo e importe de novo.

## Como separar quem pode receber

Com a base dentro, o recorte é o que decide o primeiro disparo.

1. **Quem deu opt-in.** A plataforma registra quem pediu para sair, não quem aceitou receber. Se o opt-in da loja está em outro sistema, importe a data do aceite como uma propriedade do tipo Data, ou ponha quem aceitou numa lista própria, e use isso como filtro da campanha.
2. **Quando foi a última compra.** Com uma data importada, o filtro "entre N e M dias atrás" recorta, por exemplo, quem comprou entre 30 e 90 dias atrás. É o tipo de corte que separa recompra de winback.
3. **Quem não recebe.** Quem pediu para sair e quem tem um número sem WhatsApp ficam de fora dos envios automáticos sem filtro nenhum.

Depois do recorte, comece pequeno. O limite de mensagens começa em 250 pessoas diferentes em 24 horas e sobe em degraus conforme a marca usa o teto com qualidade alta. Uma base recém-importada que sai inteira no primeiro dia bate no limite e concentra o risco.

## O que é o opt-out e de onde ele vem

O opt-out fica registrado no cliente com a data e o motivo (`optout_at` e `optout_reason`). Ele nasce de quatro jeitos:

- **A pessoa pede.** Os templates de campanha levam no rodapé o aviso "Responda com 'SAIR'", e o agente também reconhece o pedido de parar no meio da conversa.
- **A Meta avisa.** Quando a pessoa para de receber marketing da marca no próprio WhatsApp, a Meta informa, e o cliente vira opt-out.
- **A loja marca.** O time marca o opt-out manualmente no portal.
- **Vem de outra ferramenta.** Se a base antiga tinha quem pediu para sair, esse pedido continua valendo. A planilha não grava opt-out, então ele precisa ser marcado à parte.

Quem tem opt-out não recebe mensagem automática de campanha nem de jornada. O opt-out só sai se alguém do time remover, e isso deve acontecer só quando a própria pessoa pedir para voltar.

Número sem WhatsApp é outra coisa. Quando a Meta responde que o número não existe no WhatsApp, o cliente é marcado à parte (`whatsapp_unreachable_at`) e sai das audiências. A pessoa não recusou nada: se ela escrever para a loja, a marcação some sozinha.

## Erros comuns

- **Importar a agenda do celular.** Mistura cliente, fornecedor e número que não existe mais, e a rejeição vem no primeiro envio.
- **Tratar telefone como consentimento.** Comprou no site não é o mesmo que aceitou receber mensagens no WhatsApp.
- **Esquecer o opt-out da ferramenta antiga.** Quem pediu para sair lá continua pedindo para sair aqui.
- **Importar e disparar no mesmo dia.** O limite de mensagens começa baixo, e a primeira mensagem para uma base nova precisa ser testada numa fatia.
- **Iniciar uma jornada sem querer.** Se a lista do import tem uma jornada publicada, revise a opção antes de importar.
- **Data em formato americano.** 03/04/2026 é sempre 3 de abril. Se a planilha veio em mês/dia, converta antes.
- **Duas chaves para o mesmo campo.** "cidade" e "Cidade" viram dois campos, e o filtro pega só metade da base.

## Como a ztgrowth faz

- **Base a partir da loja.** Clientes e pedidos vêm da integração com Shopify, VTEX ou Wake, e a squad cuida do import histórico no onboarding, inclusive dos pedidos de uma loja VTEX antiga.
- **Import histórico sem mensagem.** Pedido antigo entra como registro, com a data dele, sem disparar jornada, cupom ou recuperação.
- **Planilha com tipos.** Texto, número e data, com o filtro "entre N e M dias atrás" para recortar por qualquer data importada.
- **Opt-out que a planilha não mexe.** Quem pediu para sair fica registrado no cliente e sai dos envios automáticos.
- **Número sem WhatsApp à parte.** Não é opt-out, e some quando a pessoa escreve.
- **Volta à base em ondas.** O primeiro disparo para uma base nova sai em ondas, com travas de entrega e opt-out, e pausa quando a qualidade do número deixa o verde.

Se a base vem de uma ferramenta não oficial, o guia [como sair da API não oficial do WhatsApp sem perder a base](https://www.ztgrowth.com.br/guia/migrar-api-nao-oficial-whatsapp/) mostra a ordem da migração.

## Perguntas frequentes

### Posso importar contatos que nunca falaram com a loja no WhatsApp?

Pode importar, mas só deve mandar mensagem ativa para quem deu opt-in para receber mensagens da marca no WhatsApp. Importar serve também para o agente reconhecer o cliente quando ele escrever.

### O que acontece com quem já está na base quando eu importo de novo?

O cliente é reconhecido pelo WhatsApp e atualizado. Célula em branco não apaga o que já existe, e o opt-out não muda.

### Importar o histórico de pedidos manda mensagem para os clientes?

Não. O import histórico grava os pedidos com a data deles e não dispara jornada, cupom nem recuperação de carrinho.

### Como tiro da lista quem pediu para sair?

Quem tem opt-out registrado já fica fora dos envios automáticos. Se o pedido de saída está em outra ferramenta, ele precisa ser marcado à parte, porque a planilha não altera o opt-out. Enquanto isso, deixe essas pessoas fora das listas de campanha.

### Quantos contatos cabem numa planilha?

Até 200.000 contatos por arquivo, em .csv, com a coluna de WhatsApp obrigatória.

---

Quer trazer a base da loja com a integração, o histórico e o opt-out cuidados por uma squad? [Fale com a ztgrowth](https://www.ztgrowth.com.br/lp/whatsapp-marketing/).
