Disparo em massa na API oficial do WhatsApp, pela aba Disparos

Resposta curta: disparo em massa na API oficial é template aprovado enviado para uma lista, porque quem está na lista, em geral, não te mandou mensagem nas últimas 24 horas. Com time técnico, você faz um laço chamando o endpoint de mensagens da Datafy, dentro das 500 requisições por minuto. Sem código, o painel tem a aba Disparos: você cria uma campanha, sobe uma planilha CSV que precisa ter uma coluna chamada telefone, escolhe um template já aprovado pela Meta, seleciona a mídia se o template tiver cabeçalho de imagem, mapeia cada variável para uma coluna da planilha e escolhe entre disparar agora ou agendar. Depois do disparo, a tela mostra o status por contato, e é ali que aparece o que a Meta não entregou.

Principais pontos

• A aba existe para quem não quer programar. Pela API o resultado é o mesmo, com um laço enviando o template para cada contato.
• A planilha é CSV e precisa da coluna telefone, com os números no formato 55, DDD e número. As outras colunas viram as variáveis do template.
• O template com imagem no cabeçalho pede a mídia na hora do disparo, porque a imagem usada na criação do modelo é só exemplo.
• O agendamento usa o fuso horário local da máquina de quem agenda.
• Aceitar o envio não é entregar. A Meta pode deixar de entregar para um número válido, e o motivo aparece no status.

Antes de disparar: o que a regra exige

Duas coisas, e nenhuma delas é opcional.

A política comercial do WhatsApp só permite contatar quem forneceu o número e deu opt-in, e só permite iniciar conversa com template aprovado. Isso significa que a lista não pode ser comprada e que não existe disparo de mensagem livre para quem está fora da janela.

E o template certo não garante entrega. Template aprovado mandado para uma lista que não responde é o cenário clássico de bloqueio de número: o volume é alto, a resposta é quase zero, e a Meta lê isso como comportamento de spam. É por isso que vale colocar no template um botão que permita à pessoa responder, mesmo que o texto do botão seja algo como não tenho interesse. Quem clica respondeu, e ainda te disse quem tirar da lista. As causas de bloqueio estão aqui.

A aba de mídias vem antes

Se o template que você vai disparar tem imagem no cabeçalho, suba o arquivo antes de criar a campanha. A aba de mídias do painel recebe o upload e devolve um link pronto para usar, tanto no disparo quanto na API.

O detalhe que pega quem repete a campanha meses depois: o arquivo fica na aba de mídias por 30 dias. Passado o prazo, é preciso subir de novo. A imagem não fica lá para sempre.

Passo 1: nova campanha

Na aba Disparos, clique em nova campanha e dê um nome. O nome é interno, para você identificar a campanha na lista depois, junto com o status dela.

Passo 2: a planilha CSV

Esta é a parte que mais dá retrabalho, e são três regras.

Regra 1: o arquivo é CSV. Se você monta a lista no Google Sheets, use o menu de arquivo e baixe como CSV. Planilha de outro formato não serve.

Regra 2: tem que existir uma coluna chamada telefone. Ela não precisa ser a primeira coluna, pode estar em qualquer posição, mas o nome precisa estar na primeira linha do arquivo, como cabeçalho. Sem essa coluna com esse nome, o painel não sabe para quem enviar.

Regra 3: o número vem completo. O formato é o código do país, o DDD e o número, tudo junto, sem sinal e sem espaço.

telefone,nome,unidade
5511999999999,Maria,Centro
5541988887777,João,Batel
5541999990000,Pedro,Portão

As outras colunas são livres e são elas que alimentam as variáveis do template. O nome da coluna pode ser qualquer um, porque no passo do mapeamento você escolhe explicitamente qual coluna preenche qual variável. Se o template tem uma variável de data de aniversário, crie uma coluna para isso e pronto.

Suba a planilha no painel. Ele lista os três primeiros contatos para você conferir se a leitura ficou certa, com o telefone e os valores das outras colunas. Vale olhar: número com DDD faltando ou coluna trocada aparece aqui, antes de qualquer mensagem sair. Clique em continuar.

Passo 3: escolher o template

O painel busca e mostra os templates aprovados na Meta. Modelo em análise ou reprovado não aparece nessa lista, o que evita metade dos erros de campanha. Como criar um template.

Escolha um e avance.

Passo 4: a mídia, quando o template tem cabeçalho de imagem

Se o template escolhido tem imagem no cabeçalho, o painel pede a imagem nesse momento. Você seleciona uma das que já estão na aba de mídias.

Isso não é redundância da plataforma: é a regra da Meta aparecendo na tela. A imagem que você subiu na criação do template serve só como exemplo para a análise. No envio, a imagem precisa vir de novo, e o painel está apenas pedindo a que ela vai usar. Pela API é a mesma coisa, com o link da imagem dentro dos parâmetros do cabeçalho. Como fica no corpo da requisição.

Passo 5: mapear as variáveis

Para cada variável do template, você diz em qual coluna da planilha está o dado que vai ser injetado ali. Se o template tem a variável nome_cliente e a sua planilha tem a coluna nome, é essa ligação que você faz.

O painel monta um preview com os dados reais da primeira linha, e esse preview é o melhor momento de revisão da campanha inteira: é ali que você vê a frase completa, com nome e valores, exatamente como o cliente vai receber.

Passo 6: enviar agora ou agendar

Duas opções.

Agora. Clica e o disparo começa, com o status ficando em andamento.

Agendar para depois. Você escolhe data e hora. O fuso horário é o local, ou seja, o do computador de quem está agendando: no Brasil, o horário de Brasília; em outro país, o horário de lá. Vale lembrar disso quando quem agenda está em um fuso e a lista está em outro.

Disparo em massa de mensagens na API oficial do WhatsAppCanal DATA7 · 10 min · assistir no YouTube

O status por contato, e a mensagem de erro real da Meta

Depois do disparo, a campanha mostra o resultado por contato. Um número inexistente na planilha aparece como erro ali mesmo. Mas o caso interessante é outro: número válido que não recebe.

Aceitar a requisição e devolver um identificador confirma só que a solicitação foi recebida. O que aconteceu chega pelos eventos de status:

No painel, a aba bate-papo mostra o log dessas mensagens, com o motivo da falha. Num teste de referência da própria Datafy, um template não entregue trouxe da Meta a justificativa de que a mensagem não foi entregue para manter a saúde do ecossistema. O destinatário era um número de teste que recebia mensagens da API com frequência e nunca respondia nenhuma. A leitura é direta: a Meta passa a tratar aquele destinatário como alguém que não quer receber, e simplesmente não entrega.

Esse é o retorno mais útil que uma campanha pode dar, porque ele não é um bug para corrigir no código: é um sinal sobre a lista. Nas palavras de Israel Henrique, CTO da Datafy: "às vezes a meta simplesmente não entrega porque ela não quer. Isso acontece."

Outros motivos de falha que aparecem no mesmo lugar: número que não existe, e problema no pagamento. Cartão com saldo insuficiente ou recusado na BM gera falha de entrega, e o erro chega no status, não na resposta do envio. Como ler o log e o payload em tempo real.

O disparo não abre a janela de 24 horas

Depois de uma campanha inteira entregue, muita gente tenta responder as pessoas com mensagem livre e recebe falha. O motivo é a janela:

Quem renova o prazo é o cliente, e cada cliente tem a sua janela. Se a sua automação responde os cliques do template, guarde o horário da última mensagem recebida de cada pessoa e confira antes de enviar mensagem livre. Fora da janela, a requisição pode até voltar HTTP 200 com identificador, e a falha aparece depois no status.

Quanto custa a campanha

A Meta cobra por mensagem entregue, pela categoria do template e pelo país do destinatário. Requisição aceita não é mensagem cobrada, e linha que falhou não entra na conta.

A finalidade define a categoria, e a categoria define o preço. Uma campanha de promoção é marketing, ainda que você preferisse que fosse utilidade: a Meta avalia o conteúdo completo do template e pode reclassificar o que foi cadastrado errado, sem avisar. Valores de referência no Brasil:

Marketing e autenticação são cobrados mesmo com a janela aberta. Utilidade é cobrada fora da janela e, até 30/09/2026, não é cobrada dentro da janela; a partir de 01/10/2026, passa a ser cobrada também dentro dela. Os valores são referência para planejamento, dependem da tabela vigente e da moeda de cobrança, e não têm relação com o plano da Datafy.

Faça essa conta antes de subir a planilha. Uma lista de dez mil contatos em marketing é uma ordem de grandeza diferente da mesma lista em utilidade, e a diferença aparece no cartão da BM, não na fatura da plataforma.

Pela API, com as duas camadas de limite

Com time técnico, o mesmo resultado sai de um laço que chama o endpoint de mensagens para cada contato da lista. Comece pelos identificadores:

GET https://cloud.datafyapi.com.br/me
Authorization: Bearer sk_live_xxx

Confira os nomes exatos dos templates aprovados:

GET https://cloud.datafyapi.com.br/templates
Authorization: Bearer sk_live_xxx

E envie, uma chamada por contato, trocando o destinatário e os valores das variáveis:

POST https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages
Authorization: Bearer sk_live_xxx
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "promocao_hamburguer",
    "language": { "code": "pt_BR" },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": { "link": "https://files.datafyapi.com.br/exemplo/hamburguer.png" }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [ { "type": "text", "text": "Maria" } ]
      }
    ]
  }
}

O ritmo do laço precisa respeitar duas camadas que valem ao mesmo tempo:

Repare que o limite mais apertado, no caso de um número em coexistência, é o da Meta, e não o nosso. Existe ainda um limite por par entre a empresa e um mesmo destinatário, e a Meta não publica o valor dele: a leitura prática é não repetir envios para a mesma pessoa em sequência.

Perguntas frequentes

Qual o formato do telefone na planilha?

Código do país, DDD e número, tudo junto, na coluna chamada telefone.

A coluna telefone precisa ser a primeira?

Não. Ela pode estar em qualquer posição, mas o nome tem que estar na primeira linha do arquivo, como cabeçalho.

Posso usar uma planilha do Excel ou do Google Sheets direto?

O arquivo tem que ser CSV. No Google Sheets, o menu de arquivo baixa a planilha nesse formato.

Posso agendar o disparo?

Pode, escolhendo data e hora. O fuso horário usado é o local, ou seja, o do computador de quem agenda.

Por que um número válido não recebeu a mensagem?

A Meta pode deixar de entregar para manter a saúde do ecossistema, e foi o que apareceu num teste com um número que recebia muitas mensagens da API e nunca respondia. Falha no pagamento é outro motivo, e também chega como erro no status.

Preciso de template aprovado mesmo para a minha própria base de clientes?

Precisa, se essas pessoas não te mandaram mensagem nas últimas 24 horas. Fora da janela só sai template, e iniciar conversa por modelo aprovado é o que a política comercial permite.

A Datafy cobra por mensagem disparada?

Não. As mensagens são cobradas pela Meta, no cartão cadastrado no seu portfólio empresarial. À Datafy você paga a conexão do número.

Como decidir

Sem time técnico, use a aba Disparos: planilha CSV com a coluna telefone, template aprovado, mídia selecionada se o cabeçalho tiver imagem, mapeamento conferido no preview e disparo agora ou agendado. Com time técnico, faça o laço pela API, tratando o 429 e respeitando também o limite de mensagens por segundo da Meta.

Nos dois casos, o trabalho não termina no envio. Comece por uma campanha de três linhas com números que você controla, olhe o status de cada uma e só depois suba a lista inteira. E leia as falhas como informação sobre a lista, não como defeito da integração: quando a Meta para de entregar para um destinatário, é porque aquele destinatário não está respondendo.

Leia também

• Como criar um template de WhatsApp passo a passo
• Como enviar um template pela API oficial
• Número banido no WhatsApp: o que fazer
• Como ver o payload das mensagens em tempo real