Pular para o conteúdo principal

Campanhas

Campanhas mandam uma mensagem (template) para muitos contatos com o cuidado de quem respeita quem recebe. Você escolhe os destinatários direto da sua base de contatos, monta a mensagem e o bZapper cuida do ritmo, do ramp-up e da proteção dos seus números — sozinho.

Requisitos

Campanhas são um add-on do plano Pro. No trilho não oficial exigem, por padrão, 2 números conectados e fora do ramp-up (7+ dias). Com menos que isso a API responde 409 campaign_needs_warmed_numbers. O mínimo de números e a janela de ramp-up são configuráveis por conta (fale com o suporte) — o padrão de 2 existe porque a distribuição entre números é o que reduz o risco de bloqueio.

Escolha os destinatários da sua base (sem planilha, sem JSON)​

Em vez de colar uma lista, você busca e seleciona contatos com filtros:

  • Busca textual (nome, telefone, e-mail);
  • Filtro por tags e grupos de contato;
  • ou "selecionar todos" que casam o filtro.
Segurança na seleção

Só entram contatos válidos: o servidor força status = active e nunca inclui bloqueados, opt-out, inalcançáveis ou pendentes de validação — independente do que for pedido. A supressão é rechecada no momento do envio. É impossível, pela ferramenta, mandar para quem pediu para sair.

Na API, POST /campaigns/{id}/recipients aceita:

{ "contact_ids": ["<uuid>", "..."] }              // seleção explícita
{ "contact_filter": { "tags": ["vip"], "groups": ["sp"] } }  // todos que casam
{ "contact_filter": { "search": "maria" }, "replace": true } // troca a lista (rascunho)

Os telefones são resolvidos no servidor, só entre contatos ativos. replace: true substitui a lista inteira (só antes de iniciar).

Num projeto da API oficial​

Num projeto oficial a campanha muda em três pontos, todos pelo mesmo motivo — o número é da Meta, não um número pareado por QR:

  • Cada variação é um template aprovado, não texto livre. Texto livre só alcança quem escreveu nas últimas 24 horas, e campanha é justamente para quem não escreveu. Várias variações de template viram um teste A/B entre templates.
  • Sem ramp-up e sem mínimo de números. Um número conectado basta. Quem limita o volume é a Meta (TIER_250, TIER_1K… contatos novos por dia), e o limite sobe sozinho com a qualidade.
  • Sem ritmo anti-bloqueio. Os intervalos de 30–90 s existem para proteger número de QR; na Cloud API eles só atrasariam a entrega.
{
  "name": "Promoção de outubro",
  "variations": [
    { "body": "", "template": { "name": "promo_outubro", "language": "pt_BR",
                                "variables": ["{nome}", "OUTUBRO10"] } }
  ]
}

Conferimos tudo ao criar: template inexistente volta 404 template_not_found, template que não está aprovado volta 422 template_not_approved, e número de variables diferente do que o corpo espera volta 422 template_variables_mismatch dizendo quantos eram. Cada variável aceita {coluna} da lista, como o corpo de texto. No painel, a tela de nova campanha já mostra o seletor de templates aprovados num projeto oficial.

Mensagem: imagem + texto, com variações​

  • Imagem-cabeçalho (opcional): suba um PNG/JPEG/WebP (até 5 MB) via POST /campaigns/media — devolve uma URL pública que vai em variations[].media.
  • Texto com variáveis ({nome}): personalize por contato — use até 3 variações para reduzir o padrão e o risco de bloqueio.

No painel de criação você vê uma prévia de como a mensagem chega no WhatsApp e um resumo em tempo real: quantos contatos vão receber, quantos números estão elegíveis e o tempo estimado de envio (GET /campaigns/estimate?recipients=&pacing=).

Acionamento: manual ou agendado​

  • Manual — a campanha fica salva como rascunho; você clica em Iniciar quando quiser disparar.
  • Agendado — escolha data e hora; a campanha dispara sozinha no horário (start_at no futuro).
Janela de envio: 08h–21h, horário de Brasília

Campanha só envia entre 08h e 21h (America/Sao_Paulo) — proteção contra bloqueio do WhatsApp. Fora da janela ela espera, não falha: se você agendar para 06h, ela começa às 08h; se iniciar às 22h, começa às 08h do dia seguinte. Enquanto espera, GET /campaigns, GET /campaigns/{id} e a resposta de POST /campaigns/{id}/start trazem:

{ "waiting": "fora da janela de envio (08h–21h, horário de Brasília) — começa às 08:00 de 22/09",
  "starts_at": "2026-09-22T11:00:00Z" }

Os dois campos só aparecem quando a campanha está agendada/em andamento e parada pela janela.

Editável até iniciar

Enquanto está rascunho ou agendada, a campanha pode ser editada (nome, ritmo, agendamento, mensagem e destinatários) via PATCH /campaigns/{id}. Depois de iniciada, vira somente visualização (409 se tentar editar).

Acompanhamento​

A lista de campanhas mostra, por campanha, os KPIs ao vivo (enviados, entregues, pendentes, falhas) com barra de progresso, e tem filtro por status e por título.

Abrindo uma campanha iniciada você vê o detalhamento por contato (GET /campaigns/{id}/recipients): nome do contato e o status real de entrega — enviado, entregue e lido (pelos recibos do WhatsApp), além de falhas (com motivo) e suprimidos. Filtre por Enviados / Entregues / Lidos / Pendentes / Falhas.

Os controles de envio​

Por baixo, todo envio passa pelos mesmos controles:

  • Ritmo controlado (perfil conservador ou normal) com intervalo entre envios;
  • Ramp-up obrigatório — número novo (< 7 dias) não entra;
  • Vários números (2+ conectados há 7+ dias), com failover se um ficar indisponível;
  • Janela de horário comercial;
  • Auto-pausa inteligente — se o bloqueio inferido subir, a campanha pausa sozinha e o número problemático é penalizado.

Você foca na mensagem e na lista; o bZapper cuida do ritmo e da distribuição.