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 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, 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, 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.
- 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.
- 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.
- 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 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.