Campanhas no painel: como funcionam, o que validar antes do Run

No produto, campanha é um registro reutilizável: você escolhe um template, marca em quais canais aquele disparo vale (WhatsApp, Telegram, SMS e/ou e-mail), define o público por segmento salvo ou por lista explícita de IDs de contato, e quando estiver pronto dispara com um clique. Não é um motor paralelo: ao rodar, entra no mesmo fluxo de filas e cobrança que você já usa pela API.

No painel, o caminho é Audience & campaigns → aba Campaigns → New campaign. É obrigatório ter ao menos um template criado antes. O formulário pede nome, template (com a categoria visível), um ou mais canais, audiência (Segment ou Contact IDs), opcionalmente instância de WhatsApp e remetente de e-mail, e ainda variáveis extras em JSON que entram na mesclagem de todos os destinatários.

Se a audiência for por segmento, na hora do Run o backend reaplica a definição JSON do segmento e busca contatos do workspace até um teto grande (ordem de dez mil por execução). Se for por IDs, você cola os CUIDs separados por vírgula ou espaço. Em ambos os casos, para cada canal só entram destinatários com dado compatível: telefone para WhatsApp/SMS, e-mail para e-mail.

Templates de marketing passam pelo mesmo filtro de consentimento que envios avulsos: o contato precisa aceitar marketing em geral e, se o template estiver vinculado a um tópico, também respeitar a inscrição naquele tópico. Quem não passa simplesmente não recebe naquela rodada—não estoura erro por contato, a lista efetiva fica menor.

Antes de enfileirar mensagens, o sistema valida variáveis obrigatórias do texto (assunto, HTML, SMS, WhatsApp) para cada telefone e cada e-mail que será usado. Faltou placeholder para alguém, o Run falha com erro explícito indicando destinatário e variáveis faltando. Por isso vale padronizar propriedades no cadastro ou usar valores padrão no template.

Variáveis globais da campanha são um objeto JSON opcional, mesclado por cima das variáveis do contato (nome, e-mail, telefone, propriedades customizadas). Exemplo de cupom igual para todos:

{
  "discount": "10",
  "campaign_name": "abril_2026"
}

Para marketing, se o template estiver configurado para anexar link de preferências, o sistema gera token por contato e preenche preferences_link automaticamente no merge—útil em e-mail sem editar o HTML na mão.

WhatsApp exige instância ativa: você escolhe uma no formulário ou deixa o padrão do workspace. Sem instância válida, o Run retorna erro. E-mail exige domínio verificado: remetente explícito ou domínio padrão do workspace; caso contrário a execução para antes de gastar crédito.

Há outras travas de segurança e tamanho: corpo de e-mail e assunto após substituição têm limites; SMS é truncado e passa por validação de conteúdo; há proteção contra SMS duplicado recente para o mesmo texto e número; filas por canal podem recusar se o backlog do workspace estiver cheio. Créditos e status do plano também são checados antes de marcar a campanha como em execução.

Durante o Run o status vai para RUNNING e, ao terminar com sucesso, COMPLETED; se algo falhar no meio, FAILED com mensagem resumida na tabela. Enquanto RUNNING, não dá para editar ou apagar a campanha. O botão Run dispara imediatamente—não depende de agendamento interno da campanha para essa ação.

Boas práticas: usar Preview no segmento antes de associar à campanha; fazer um disparo teste com poucos IDs; conferir categoria do template (marketing vs transacional); garantir que cada canal selecionado tenha conteúdo preenchido no template; monitorar créditos e erros na lista. Assim campanha vira ferramenta de operação recorrente, não loteria na véspera.

Em resumo: campanha no painel concentra template, canais e público; o Run aplica regras de negócio e infraestrutura do produto e só então enfileira envios. Dominar esses pré-requisitos evita falha em massa e alinha marketing, engenharia e financeiro na mesma página.