> For the complete documentation index, see [llms.txt](https://ajuda.digitalsac.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.digitalsac.io/digicrm/operacao-uso-do-sistema/campanha-whatsapp.md). # 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 | | ------------- | ---------------------------------------------------------------------- | | # | ID | | 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 | 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]] *** ### Como criar (passo a passo do modal) 1. Clique em **Adicionar**. 2. Preencha os **dados da campanha** (tabela abaixo). 3. Escolha o **modo de envio** (apenas um por campanha): **Mensagens**, **Mensagem Interativa** ou **Carousel**. 4. (Opcional) Expanda **Configurações avançadas** e habilite a régua/automação. 5. Confira o **preview** no celular simulado. 6. 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 | 7 | | **Fechar sem resposta após (dias)** | Não (1–365) | Marca jornada como `closed_no_reply` | 15 | | **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 | 1 | | **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]] #### Incluir contatos (modal) 1. Clique em **Incluir Contatos**. 2. Expanda **Filtros (Data criação do contato)** se quiser filtrar. 3. Escolha tipo: **Contatos** ou **Grupos**. 4. Clique em **Gerar** (ou use a busca). 5. Selecione na tabela (seleção múltipla). 6. 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 | | 0 | Envio Pendente | | 1 | Entrega Pendente | | 2 | Recebida | | 3 | Lida | | 4 | 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: 1. Data/hora de início **≥ dia atual** (senão: *Não é possível programar campanha com data menor que a atual*). 2. Pelo menos **1 contato** vinculado (senão: *Necessário ter contatos vinculados para programar a campanha*). 3. 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**. 1. Informa o nome da nova campanha (padrão: `{nome} - Cópia`). 2. Cria campanha com mensagens, delay, conexões e mídia (quando houver). 3. 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 1. **Comprar Créditos** na lista. 2. Informe o **valor em R$**. 3. O sistema calcula créditos: `floor(valor / valueCredit do plano)` — **1 crédito = 1 mensagem**. 4. **Comprar** gera QR Code PIX (copia e cola). 5. 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 | Não | Não | Sim | Sim | Sim | Sim | Sim\* | | **Programada** (`scheduled`) | Não | Sim | Não | Sim | Não | Não | Não | Sim | Sim\* | | **Processando** (`processing`) | Não | Sim | Não | Sim | Não | Não | Não | Sim | Sim\* | | **Pausada** (`paused`) | Não | Não | Sim | Não | Não | Não | Não | Sim | Sim\* | | **Finalizada** (`finished`) | Não | Não | Não | Não | Não | Não | Não | Sim | Sim\* | | **Cancelada** (`canceled`) | Sim | Não | Não | Não | Sim | Não (UI)† | Sim | 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]]