Disparo em massa pela API oficial do WhatsApp: como fazer sem perder o número

Atualizado em 20/10/2026

Disparo em massa pela API oficial do WhatsApp é o envio de um template de marketing aprovado pela Meta para uma lista de pessoas que deram consentimento para receber mensagens da sua empresa. O volume é controlado por três limites: quantas pessoas o portfólio pode alcançar em 24 horas, quantas mensagens de marketing cada usuário aceita receber e quantas mensagens por segundo o número envia. Para destinatários no Brasil, cada template de marketing entregue custa R$ 0,3217 na tabela da Meta, e listas sem opt-in geram bloqueios e denúncias que levam a restrições na conta.

Este guia cobre o que a Meta exige, como planejar a campanha, quanto custa e um exemplo de envio em Node.js com tratamento dos erros que importam.

O que a Meta exige para envio em massa

A API não tem um endpoint de “disparo”. Cada mensagem é uma chamada de envio de template para um destinatário. O que transforma isso em campanha é o seu sistema: lista, agendamento, controle de ritmo e leitura dos status.

Três regras valem para qualquer campanha:

Template aprovado. Fora da janela de 24 horas aberta pelo cliente, só é possível enviar templates. Para promoções, ofertas e novidades, a categoria é marketing. Veja templates da API do WhatsApp.
Opt-in. A empresa precisa do número do cliente e de uma permissão confirmando que ele quer receber mensagens dela.
Respeito ao opt-out. A política exige atender a todos os pedidos para parar de receber mensagens, feitos dentro ou fora do WhatsApp.

Opt-in: o que a Meta pede e como registrar

A página Get opt-in for WhatsApp lista três requisitos:

Deixar claro que a pessoa está aceitando receber comunicações da empresa.
Deixar claro o nome da empresa de quem ela vai receber mensagens.
Cumprir a legislação aplicável.

Desde a atualização da política de novembro de 2024, o opt-in pode ser geral, sem citar o WhatsApp especificamente, desde que cumpra a lei local. O método fica a critério da empresa: site, SMS, ligação com URA, papel assinado na loja. A Meta recomenda opt-ins separados por categoria de mensagem (pedidos, ofertas, recomendações), porque isso reduz o risco de bloqueio por mensagem inesperada.

Um texto de checkbox que atende aos requisitos:

“Quero receber ofertas e novidades da Loja Exemplo por WhatsApp. Posso cancelar quando quiser respondendo SAIR.”

Guarde a prova do consentimento junto do contato. Se houver contestação, é esse registro que mostra quando e como a pessoa aceitou:

{
  "wa_id": "5584999999999",
  "optin": {
    "categoria": "marketing",
    "origem": "checkout_site",
    "texto_aceito": "Quero receber ofertas e novidades da Loja Exemplo por WhatsApp.",
    "aceito_em": "2026-10-12T14:32:10-03:00",
    "ip": "200.0.0.10"
  },
  "optout": null
}

Além da política da Meta, o tratamento desses dados está sujeito à LGPD. Consulte o jurídico da empresa sobre base legal, prazo de guarda e forma de revogação.

Opt-out dentro do WhatsApp

Há dois caminhos de saída que o seu sistema precisa tratar:

Botão no template. Inclua um botão de resposta rápida como “Não quero ofertas”. Quando o cliente toca nele, o webhook chega com type: "button" e o texto do botão em button.text. Marque o contato como opt-out na hora.
Configuração do próprio WhatsApp. O usuário pode parar as mensagens de marketing da sua empresa pela opção “Ofertas e anúncios”. Se você tentar enviar mesmo assim, o webhook de status volta com failed e erro 131050, segundo a documentação de templates de marketing. Trate esse erro como opt-out.

Os limites que controlam o volume

Limite	Como funciona	Erro ou sinal	O que fazer
Limite de mensagens do portfólio	Destinatários únicos fora da janela de atendimento em 24 h móveis: 250, 2.000, 10.000, 100.000 ou ilimitado	Nível atual no WhatsApp Manager e no campo `whatsapp_business_manager_messaging_limit`	Distribua a campanha em dias e acompanhe o nível no WhatsApp Manager
Limite por usuário de marketing	A Meta limita quantos templates de marketing cada pessoa recebe de todas as empresas, conforme o engajamento recente dela	Status `failed` com erro `131049`	Não reenvie antes de 24 horas
Taxa de envio (throughput)	Até 80 mensagens por segundo por número, por padrão	Erro `130429` na resposta da API	Reduza o ritmo e tente de novo com espera crescente
Qualidade do template	Templates com qualidade baixa são pausados: 3 horas na primeira vez, 6 horas na segunda e desativados na terceira	Webhook de status do template	Pare a campanha que usa o template pausado

Fontes: limites de mensagens, limites por usuário de marketing, throughput e pausa de templates.

Dois detalhes que surpreendem quem planeja a primeira campanha:

O limite é do portfólio, não do número. Desde outubro de 2025, todos os números de um portfólio compartilham o mesmo limite. Comprar mais números não multiplica o alcance.
O limite por usuário independe de você. Mesmo com opt-in, parte dos destinatários pode não receber porque já recebeu muito marketing de outras empresas. Mensagens de marketing enviadas dentro de uma janela de atendimento aberta pela resposta do cliente não contam para esse limite.

O artigo limite de mensagens da API do WhatsApp detalha como subir de nível.

Segmentação: menos contatos, mais resultado

O limite por usuário leva em conta a taxa de leitura recente da pessoa. Na prática, mandar para quem não lê piora a entrega para todos. Segmentar bem é a forma mais direta de melhorar o resultado:

Recência. Priorize quem comprou, respondeu ou abriu uma mensagem nos últimos meses.
Interesse declarado. Use a categoria escolhida no opt-in. Quem aceitou “pedidos” não aceitou “ofertas”.
Histórico de falhas. Retire contatos com 131050 e reduza a frequência para quem acumula 131049.
Frequência. Defina um teto de campanhas por contato por semana no seu próprio sistema.
Personalização. Variáveis com nome, último produto ou cidade tornam a mensagem esperada. A Meta lista mensagens personalizadas e úteis entre as boas práticas de qualidade.

Quanto custa um disparo

Desde 1º de julho de 2025, a Meta cobra por mensagem entregue, e não por conversa. Para destinatários no Brasil, a tarifa de marketing em vigor desde 1º de outubro de 2026 é de R$ 0,3217 por mensagem, e marketing não tem desconto por volume (página de preços e tabela no site do WhatsApp Business).

Tamanho da campanha	Custo Meta estimado (Brasil, marketing)
1.000 entregues	R$ 321,70
10.000 entregues	R$ 3.217,00
50.000 entregues	R$ 16.085,00

Mensagens com falha não são cobradas. Mensagens dentro da janela de ponto de entrada gratuito, aberta quando o cliente chega por um anúncio de clique para o WhatsApp, também não. O artigo de preços da API no Brasil traz as outras categorias e o cálculo pelo webhook de status.

Na Vectalk, você não cadastra cartão na Meta: o custo das mensagens entra na fatura da Vectalk, e a Vectalk paga a Meta.

Por que listas compradas derrubam o número

Uma lista comprada ou “raspada” de grupos falha no requisito mais básico: as pessoas nunca deram opt-in para a sua empresa. O efeito aparece em cadeia:

Feedback negativo. A Meta calcula a qualidade das mensagens com base nos últimos sete dias, a partir de bloqueios, denúncias, silenciamentos, arquivamentos e motivos informados no bloqueio (qualidade das mensagens).
Template pausado. Com qualidade baixa, o template entra em pausa e, na terceira vez, é desativado. A campanha para no meio.
Limite congelado. O aumento automático de limite exige mensagens de alta qualidade em todos os números e templates.
Restrições na conta. A política prevê restringir o acesso ou limitar o envio de quem recebe muito feedback negativo. A documentação de aplicação de políticas descreve bloqueios de 1 ou 3 dias para templates, de 5, 7 ou 30 dias para qualquer mensagem, bloqueio por tempo indeterminado e, por fim, desativação da conta na plataforma.

Trocar de número não resolve: o limite e a reputação ficam no portfólio. O artigo número bloqueado na API do WhatsApp mostra como diagnosticar e recorrer.

Exemplo: disparo com controle de ritmo em Node.js

O script abaixo envia um template de marketing pela Vectalk para uma lista já filtrada por opt-in, com ritmo controlado e nova tentativa no erro de throughput. O payload é o mesmo da Cloud API.

const VECTALK = 'https://apis.vectalk.com.br/api/messages';
const TOKEN = process.env.VECTALK_TOKEN;
const POR_SEGUNDO = 20; // bem abaixo do teto padrão de 80 mps

const pausa = (ms) => new Promise((r) => setTimeout(r, ms));

async function enviarTemplate(contato, tentativa = 1) {
  const r = await fetch(VECTALK, {
    method: 'POST',
    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: contato.wa_id,
      type: 'template',
      template: {
        name: 'oferta_semana',
        language: { code: 'pt_BR' },
        components: [
          { type: 'body', parameters: [{ type: 'text', text: contato.nome }] },
        ],
      },
    }),
  });

  const corpo = await r.json();
  if (r.ok) return { wa_id: contato.wa_id, wamid: corpo.messages[0].id };

  const codigo = corpo.error?.code;
  if (codigo === 130429 && tentativa <= 5) {
    await pausa(1000 * 2 ** tentativa); // espera crescente
    return enviarTemplate(contato, tentativa + 1);
  }
  return { wa_id: contato.wa_id, erro: codigo ?? r.status };
}

export async function disparar(contatos) {
  const resultados = [];
  for (let i = 0; i < contatos.length; i += POR_SEGUNDO) {
    const lote = contatos.slice(i, i + POR_SEGUNDO);
    resultados.push(...(await Promise.all(lote.map((c) => enviarTemplate(c)))));
    await pausa(1000);
  }
  return resultados; // guarde o wamid para cruzar com os status depois
}

A resposta 200 da API só diz que a mensagem foi aceita. Entrega, leitura e falhas como 131049 e 131050 chegam depois, no webhook de status:

export function tratarStatus(status, db) {
  if (status.status !== 'failed') return db.atualizarEnvio(status.id, status.status);

  const codigo = status.errors?.[0]?.code;
  if (codigo === 131050) db.marcarOptOut(status.recipient_id, 'marketing');
  if (codigo === 131049) db.agendarNoMinimoEm(status.recipient_id, 24 * 60 * 60 * 1000);
  db.atualizarEnvio(status.id, 'failed', codigo);
}

Se a sua lista passa de algumas centenas de contatos, rode o envio num worker com fila persistente, para retomar de onde parou se o processo cair.

Checklist antes de apertar “enviar”

Template de marketing aprovado, com botão de saída.
Lista filtrada por opt-in de marketing e sem contatos com opt-out.
Volume da campanha dentro do limite atual do portfólio.
Ritmo de envio abaixo do throughput do número.
Webhook de status registrando entregas, leituras e falhas.
Alguém acompanhando a qualidade do template nas primeiras horas.

Perguntas frequentes

Posso enviar texto livre em massa?

Não. Texto livre só é permitido dentro da janela de 24 horas aberta pelo cliente. Para iniciar contato com uma lista, é preciso template. Veja janela de 24 horas do WhatsApp.

Com quantos contatos posso começar?

Um portfólio novo alcança 250 destinatários únicos em 24 horas fora da janela de atendimento. A verificação da empresa é um dos caminhos para chegar a 2.000. Depois disso, o limite sobe automaticamente com qualidade e uso.

Mensagem com erro 131049 é cobrada?

A Meta cobra apenas mensagens entregues. Uma mensagem com status failed não é entregue e, portanto, não entra na cobrança.

Posso usar um template de utilidade para promoção, que é mais barato?

Não. A Meta classifica conteúdo promocional como marketing e pode recategorizar o template. Quem insiste pode ter os templates de utilidade convertidos em marketing e a criação de novos templates de utilidade bloqueada por um período.

Vale a pena ter vários números para disparar mais?

Não para alcance. O limite é calculado por portfólio e compartilhado por todos os números. Vários números podem fazer sentido por organização (marcas, departamentos), não para contornar limite.

Comece na Vectalk

A Vectalk dá acesso à API oficial com os mesmos payloads e webhooks da Meta e um token para todas as contas. Você paga a Vectalk, e a Vectalk paga a Meta, sem cartão cadastrado na Meta. Crie sua conta em apps.vectalk.com.br/register ou fale com o time pela página de contato para planejar sua primeira campanha.

Fontes oficiais consultadas em 20/10/2026: Get opt-in for WhatsApp, Política de Mensagens do WhatsApp Business, Limites de mensagens, Limites por usuário de marketing, Templates de marketing, Throughput, Pausa de templates, Aplicação de políticas, Preços, Tabela de preços no site do WhatsApp Business.