Pular para o conteúdo principal

Campanhas

Campanhas mandam uma mensagem (template) para muitos contatos com a cautela de 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 e 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).

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;
  • Rotação de números (com 2+ aquecidos) para diluir o volume;
  • 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.