Campanha WhatsApp

Campanha WhatsApp (não-WABA) dispara mensagens em massa por conexões WhatsApp não oficiais (whatsapp / Baileys e whatsmeow), com saldo de créditos, fila de envio (BullMQ), status do ciclo de vida e gestão de audiência (contatos, grupos, CSV/XLSX).

O envio em massa consome créditos do tenant (campaignMessages). Cada crédito equivale a 1 mensagem. Há aviso explícito de risco de banimento do número WhatsApp.

[[FOTO]]

Dashboard da lista

Ao abrir Campanhas, a tela mostra três blocos de resumo e depois a listagem.

Cards superiores

Card

O que calcula

Total de Campanhas

Quantidade total de campanhas do tenant

Campanhas Ativas

Contagem com status scheduled ou processing

Mensagens Enviadas

Soma de mensagensEnviadas de todas as campanhas

Taxa de Sucesso

% = campanhas finished ÷ (todas − pending)

Créditos Disponíveis

Campo campaignMessages do tenant

Contagem por status

Exibe contadores para: Pendente, Programada, Processando, Pausada, Finalizada, Cancelada.

Últimos 3 meses

Para o mês atual, anterior e retrasado: quantidade de campanhas, contatos e mensagens (pela data de start ou createdAt).

Barra de ações da lista

Controle

Função

Alternar Tabela / Cards

Preferência salva em localStorage (campaignsViewMode)

Comprar Créditos

Abre modal PIX de créditos

Adicionar

Abre modal de criar campanha

Atualizar

Recarrega a listagem

Filtros

Mês e Ano (sobre a data de início da campanha)
Paginação: 15 / 30 / 50 / 100 por página (tabela)

Colunas da tabela

Coluna

Conteúdo

Campanha

Nome

Início

Data/hora de início

Status

Pendente / Programada / Processando / Pausada / Cancelada / Finalizada

Qtd. Contatos

Total vinculados

À Enviar

Pendentes de envio

À Entregar

Pendentes de entrega

Recebidas

Entregues

Lidas

Ações

Ícones de operação (ver seções abaixo)

Visualização em cards

Cada card mostra: nome, ID, badge de status, data de início, contadores (contatos, à enviar, recebidas, lidas) e ações. Relatório PDF e CSV só existem na visão em tabela.

[[FOTO]]

Clique em Adicionar.
Preencha os dados da campanha (tabela abaixo).
Escolha o modo de envio (apenas um por campanha): Mensagens, Mensagem Interativa ou Carousel.
(Opcional) Expanda Configurações avançadas e habilite a régua/automação.
Confira o preview no celular simulado.
Clique em Salvar.

O cabeçalho do modal informa: “As mensagens sempre serão enviadas em horário comercial e dias úteis.”

[[FOTO]]

Campos do formulário — dados gerais

Nome (UI)

Obrigatório

Para que serve

Nome da Campanha

Sim

Identificação da campanha

Data/Hora início

Sim

Momento a partir do qual o agendamento/envio pode começar. Não pode ser anterior ao dia atual

Enviar por (conexões)

Sim (≥ 1)

Conexões WhatsApp usadas no disparo. Só listam conexões whatsapp ou whatsmeow com status CONNECTED. Admin/master vê todas; demais usuários podem ser filtrados por allowedConnections. Múltiplas conexões = distribuição randômica

Intervalo de mensagem aleatória por minimo (delay)

Sim (padrão 20 s)

Tempo mínimo entre mensagens (aleatoriedade)

Intervalo de mensagem aleatório por máximo (maxDelay)

Não (padrão 30 s)

Tempo máximo entre mensagens

Horário de Início (startTime)

Não (padrão 08:00)

Início da janela diária de envio

Horário de Fim (endTime)

Não (padrão 20:00)

Fim da janela diária de envio

Mídia

Não

Anexo opcional (upload ou Galeria). Máx. 10 MB por arquivo. Aceita imagem, PDF, DOC/DOCX, MP4, XLS/XLSX, ZIP, PPT/PPTX. Desabilitada nos modos Interativa e Carousel

Dica na tela: envios respeitam o horário definido e dias úteis.

[[FOTO]]

Modo de envio (mutuamente exclusivo)

Modo

Valor interno

Obrigatório no modo

Para que serve

Mensagens

text

As três mensagens

Envia até 3 textos (sorteados/usados no fluxo de texto) + mídia opcional

Mensagem Interativa

buttons

Corpo + ≥ 1 botão

Mensagem com botões (até 3). Sem mídia anexa nesta tela

Carousel

carousel

Template de carousel

Usa template cadastrado; cada card já tem sua mídia/botões

Trocar de modo com conteúdo preenchido pede confirmação e apaga o conteúdo do modo anterior (e a mídia, se o novo modo não a suporta).

Modo Mensagens — campos

Nome

Obrigatório

Para que serve

1ª Mensagem

Sim

Texto 1 (emoji, variáveis, botão de IA)

2ª Mensagem

Sim

Texto 2

3ª Mensagem

Sim

Texto 3

Variáveis disponíveis: {{name}} (Nome), {{greeting}} (Saudação).

Há aviso de risco de banimento por envio em massa.

Modo Mensagem Interativa — campos

Nome

Obrigatório

Para que serve

Corpo da mensagem

Sim (máx. 1024)

Texto acima dos botões

Rodapé

—

Removido da UI neste fluxo (Baileys/Whatsmeow não exibe rodapé aqui); campo interno fica vazio

Botões (até 3)

≥ 1

Cada botão: tipo + texto (+ valor se não for “resposta rápida”)

Tipos de botão:

Tipo

Valor necessário

Resposta rápida (reply)

Só o texto do botão

Abrir link (url)

URL

Ligar (call)

Telefone

Copiar código (copy)

Código a copiar

Aviso na tela: botões interativos podem ter maior taxa de banimento.

Modo Carousel — campos

Nome

Obrigatório

Para que serve

Template de Carousel

Sim

Template já cadastrado (com cards válidos)

[[FOTO]]

Configurações avançadas (régua / resposta / Kanban)

Painel expansível no final do modal. Se o interruptor mestre estiver desligado, a campanha é “simples” e as automações abaixo não são aplicadas.

Nome

Obrigatório

Para que serve

Padrão

Habilitar configurações avançadas

Não

Liga/desliga aplicação de tag, fila, usuário, carteira, Kanban etc.

Desligado (campanha simples)

Janela para considerar resposta (dias)

Não (1–365)

Respostas após o prazo não disparam tag/fila/usuário/Kanban

Fechar sem resposta após (dias)

Não (1–365)

Marca jornada como closed_no_reply

Salvar contato ao importar CSV/XLSX

Não

Se desligado, números ficam só no item da campanha (origin = csv)

false

Carteira (vendedor) ao enviar

Não

Aplica usuário como carteira do contato (sem sobrescrever carteira de outro)

—

Criar contato quando responder (CSV)

Não

Promove número CSV → Contact ao responder na janela

true

Tag aplicada na resposta

Não

Tag no Contact ao responder

—

Fila atribuída ao ticket

Não

Move o ticket para a fila ao responder

—

Usuário atribuído ao ticket

Não

Responsável do ticket ao responder

—

Etapas máximas

Não (1–10)

Quantidade de mensagens da régua

Permitir reenviar para não respondedores

Não

Habilita avanço de etapa para quem não respondeu

true

Tag aplicada no encerramento

Não

Tag quando fecha sem resposta

—

Criar ticket no fechamento sem resposta

Não

Necessário para Kanban no encerramento

false

Coluna do Kanban na resposta

Não

Move card ao responder

—

Coluna do Kanban no encerramento

Não

Move não respondedores (exige criar ticket no fechamento)

—

É possível criar etiqueta na hora (nome + cor) a partir dos selects de tag.

[[FOTO]]

Consentimento de marketing (opt-in / opt-out)

Assim como a Campanha WABA, esta tela também tem seções próprias de consentimento no modal (fora do interruptor mestre):

Opt-out: toggle Respeitar lista Não perturbe (padrão ligado) + palavras próprias da campanha.
Opt-in: toggle Detectar aceite de marketing (padrão ligado) + palavras próprias + Modo rigoroso (só quem tem opt-in ativo).

Ao programar o envio com algum desses toggles ativo, a tela avisa quantos contatos da audiência serão excluídos antes de confirmar. Detalhes completos na página Consentimento de marketing.

[[FOTO]]

Após salvar

Sucesso: notificação Campanha criada! / Campanha editada!
Falha de validação: Verifique se todas os campos obrigatórios estão preenchidos (ou mensagem específica do modo)
A campanha nasce com status Pendente e ainda não envia até você programar/iniciar

Como adicionar/gerir contatos

Na lista, clique no ícone Lista de Contatos da Campanha (abre /campanhas/:id).

Cabeçalho da tela de contatos

Mostra nome, data de início e status. Botão Listar Campanhas volta para /campanhas.

Métricas da audiência

Resumo (total, enviados, lidos, respondidos, sem resposta, fora da janela, conflitos de carteira, Kanban por resposta/fechamento), com atualização sob demanda.

Ações disponíveis (conforme status)

Ação

Quando aparece

Incluir Contatos

pending ou canceled

Importar CSV/XLSX

pending ou canceled

Limpar Campanha

pending ou canceled (remove todos os contatos)

Remover contato individual

pending ou canceled

Relatório consolidado

Sempre

Reenviar p/ não respondedores

finished, completed ou canceled

[[FOTO]]

Clique em Incluir Contatos.
Expanda Filtros (Data criação do contato) se quiser filtrar.
Escolha tipo: Contatos ou Grupos.
Clique em Gerar (ou use a busca).
Selecione na tabela (seleção múltipla).
Confirme Adicionar.

Filtros do modal

Nome

Obrigatório

Para que serve

Data início / Final

Não

Filtra pela data de criação do contato

País

Não

ISO do país

Estado(s) / subdivisões

Não

Regiões do país escolhido

Etiqueta(s)

Não

Filtra por tags

Carteira

Não

Filtra por carteira de usuário

Tipo Contatos / Grupos

Sim (toggle)

Lista contatos cadastrados ou grupos dos WhatsApps da campanha

Busca nome/telefone (ou grupos)

Não

Filtro textual

Grupos: sincroniza grupos das conexões selecionadas na campanha. Sem WhatsApp na campanha → erro Nenhum WhatsApp selecionado na campanha.

Importar CSV/XLSX

Arquivo com coluna número (e opcionalmente nome). Opção de salvar como Contato no sistema. Resultado mostra: lidos, importados, inválidos, duplicados, contatos criados, vínculos, carteira (aplicada / já tinha / conflitos) e avisos.

Origens possíveis na lista: Contato, CSV, XLSX, Manual.

Colunas da lista de contatos

Foto, Nome, WhatsApp, Origem, Etapa, Jornada, Status de envio (ACK), Respondido em, Carteira, Kanban, Etiquetas, Estado, Ações.

Status ACK (entrega WhatsApp):

ACK

Significado

-1

Error

Envio Pendente

Entrega Pendente

Recebida

Lida

Reproduzido

Jornada (quando régua ativa): Pendente, Enviando, Enviado, Entregue, Lido, Respondeu, Sem resposta, Falhou (+ badge “Fora da janela”).

[[FOTO]]

Como agendar / iniciar / pausar / retomar / cancelar

O botão da lista chamado Programar Envio chama a API de iniciar (POST /campaigns/start/:id). Na prática: agenda a fila e muda o status para Programada (scheduled); depois o processamento avança para Processando.

Programar / iniciar

Disponível em: pending ou canceled.

Pré-requisitos no frontend:

Data/hora de início ≥ dia atual (senão: Não é possível programar campanha com data menor que a atual).
Pelo menos 1 contato vinculado (senão: Necessário ter contatos vinculados para programar a campanha).
Status deve ser pendente ou cancelada.

Sucesso: Campanha iniciada.

Pausar

Disponível em: scheduled ou processing.

Confirmação: Deseja pausar a campanha {name}? Todas as mensagens pendentes serão interrompidas.

Resultado: status Pausada. Backend só pausa se estiver programada ou processando.

Retomar

Disponível em: paused.

Confirmação: Deseja retomar a campanha {name}?

Reenfileira contatos ainda sem envio e volta o fluxo (status tipicamente Programada / processamento). Se não houver pendências, pode finalizar.

Cancelar

Disponível em: scheduled ou processing.

Confirmação na UI; remove jobs da fila e define status Cancelada.

[[FOTO]]

Outras ações

Editar

Só Pendente ou Cancelada.
Caso contrário o botão fica desabilitado: Edição bloqueada após o envio (apenas Pendentes ou Canceladas podem ser editadas).

Duplicar

Disponível em qualquer status.

Informa o nome da nova campanha (padrão: {nome} - Cópia).
Cria campanha com mensagens, delay, conexões e mídia (quando houver).
Tenta copiar os contatos; se falhar, avisa: Não foi possível adicionar os contatos à nova campanha.

A cópia nasce pendente (nova campanha via API de criação).

Relatório PDF

Só na visão tabela. Gera PDF com informações da campanha, métricas (total, enviadas, entregues, lidas) e detalhamento por contato.

Relatório CSV

Só na visão tabela. Exporta resumo + linhas por contato (separador ;, UTF-8 com BOM).

Excluir

Botão visível apenas se status = Pendente.
Backend só permite excluir pending ou canceled.
Mensagem de restrição no frontend: só deletar pendentes/canceladas sem contatos vinculados (há confirmação irreversível).

Comprar créditos

Comprar Créditos na lista.
Informe o valor em R$.
O sistema calcula créditos: floor(valor / valueCredit do plano) — 1 crédito = 1 mensagem.
Comprar gera QR Code PIX (copia e cola).
Pague no app do banco; o saldo aparece no card Créditos Disponíveis após atualização.

Relatório consolidado (tela de contatos)

Métricas, taxas, breakdown por origem/etapa, filtros (respondeu, CSV, Kanban etc.) e exportação CSV do consolidado.

Reenviar para não respondedores

Na tela de contatos, quando a campanha está finalizada/cancelada (e a régua permite): envia a próxima etapa para quem não respondeu dentro da janela.

[[FOTO]]

Regras por status

Status

Programar/Iniciar

Pausar

Retomar

Cancelar

Editar

Excluir (UI)

Incluir/Importar/Limpar contatos

Duplicar

PDF/CSV

Pendente (pending)

Sim

Não

Sim

Sim*

Programada (scheduled)

Não

Sim

Não

Sim

Não

Sim

Sim*

Processando (processing)

Não

Sim

Não

Sim

Não

Sim

Sim*

Pausada (paused)

Não

Sim

Não

Sim

Sim*

Finalizada (finished)

Não

Sim

Sim*

Cancelada (canceled)

Sim

Não

Sim

Não (UI)†

Sim

Sim*

* PDF/CSV apenas na visualização em tabela. † Backend aceita delete em canceled, mas o botão de excluir na UI só aparece em pending.

Transições típicas:

pending → (programar) → scheduled → processing → finished
                ↘ pause → paused → (retomar) → scheduled/processing
scheduled/processing → (cancelar) → canceled → (programar de novo) → scheduled …

Campanhas presas em processing por muito tempo podem ser marcadas como finished por rotinas do backend.

[[FOTO]]

Erros comuns

Situação

Mensagem / comportamento

Data de início no passado (criar/editar)

Não pode ser inferior ao dia atual

Programar com data < hoje

Não é possível programar campanha com data menor que a atual

Programar sem contatos

Necessário ter contatos vinculados para programar a campanha

Editar após início

Só é permitido editar campanhas que estejam pendentes ou canceladas. / botão bloqueado

Excluir fora das regras

Só é permitido deletar campanhas que estejam pendentes ou canceladas e não possuam contatos vinculados.

Falha ao iniciar

Não foi possível iniciar a campanha.

Falha ao pausar / retomar / cancelar

Notificações específicas de erro com o nome da campanha

Campos incompletos no modal

Verifique se todas os campos obrigatórios estão preenchidos

Sem conexão selecionada

Obrigatório / Selecione pelo menos uma conexão

Arquivo de mídia > 10 MB

Aviso de tamanho máximo + priorizar imagem/vídeo

Nenhuma conexão CONNECTED

Nenhuma conexão disponível

Incluir grupos sem WhatsApp na campanha

Nenhum WhatsApp selecionado na campanha…

Falha ao importar CSV

Falha ao importar

Falha ao gerar PDF/CSV

Erro ao gerar relatório / Erro ao gerar relatório em CSV

Duplicar sem conseguir copiar contatos

Aviso amarelo (campanha criada, contatos não copiados)

PIX de créditos

Ocorreu um erro! se a geração falhar

Conflito de carteira na audiência

Tooltip: carteira da campanha não foi aplicada

[[FOTO]]

Dicas

Use conexões CONNECTED e, se possível, mais de uma para diluir o volume (envio randômico).
Ajuste delay / maxDelay e a janela 08:00–20:00 (ou a que configurar) para reduzir risco de banimento; a própria tela recomenda moderação.
As três mensagens do modo texto são todas obrigatórias — prepare variações antes de salvar.
Inclua contatos antes de programar; sem audiência o start é bloqueado.
Prefira importar CSV sem “salvar contato” se a lista for descartável (não polui a base).
Ative configurações avançadas só quando precisar de tag/fila/Kanban/régua; desligadas = campanha simples.
Para acompanhar entregas, use a lista de contatos (ACK) e o relatório consolidado; use PDF/CSV na visão tabela para auditoria.
Monitore créditos antes de disparos grandes (1 crédito = 1 mensagem).
Diferencie sempre esta tela da Campanha WABA: aqui não há templates oficiais Meta; usa Baileys/Whatsmeow.

[[FOTO]]

AnteriorMensagens Agendadas

PróximoCampanha WABA

Atualizado há 27 dias

Dashboard da lista

Cards superiores

Contagem por status

Últimos 3 meses

Barra de ações da lista

Filtros

Colunas da tabela

Visualização em cards

Como criar (passo a passo do modal)

Campos do formulário — dados gerais

Modo de envio (mutuamente exclusivo)

Configurações avançadas (régua / resposta / Kanban)

Consentimento de marketing (opt-in / opt-out)

Após salvar

Como adicionar/gerir contatos

Cabeçalho da tela de contatos

Métricas da audiência

Ações disponíveis (conforme status)

Incluir contatos (modal)

Importar CSV/XLSX

Colunas da lista de contatos

Como agendar / iniciar / pausar / retomar / cancelar

Programar / iniciar

Pausar

Retomar

Cancelar

Outras ações

Editar

Duplicar

Relatório PDF

Relatório CSV

Excluir

Comprar créditos

Relatório consolidado (tela de contatos)

Reenviar para não respondedores

Regras por status

Erros comuns

Dicas