Documentação / Estratégias internas da Pilot Status para disparo em massa e campanhas MARKETING

Estratégias internas da Pilot Status para disparo em massa e campanhas MARKETING

Entrar

Estratégias internas da Pilot Status para disparo em massa e campanhas MARKETING

Este documento descreve o que a plataforma faz automaticamente para ajudar quem envia muitas mensagens de template MARKETING (disparo em massa ou campanhas), reduzindo padrões que parecem “robô” ou campanha agressiva — no tempo (fila) e no texto (conteúdo).

Para detalhes operacionais de variáveis de ambiente, veja também marketing-worker-anti-spam.md. Para uma simulação numérica de lote (ex.: 100 mensagens), veja simulacao-anti-spam-100-mensagens-marketing.md.

1. Princípio geral: API registra intenção, worker aplica o ritmo

  • API / fullstack cria a mensagem QUEUED, persiste o snapshot do pedido (message_send_requests) e enfileira o job. Para MARKETING, não calcula o atraso “humano” nem o micro-batch: só grava intenção no renderPlan (ex.: humanJitter, irregularBatch com applied: false).
  • Worker é quem calcula atrasos, persiste deliverBy quando precisa esperar, e só então renderiza, opcionalmente reescreve o texto com IA, aplica guardrails e envia.

Isso vale igual para:

  • POST /v1/messages/send (API pública),
  • envio pela tela Mensagens (/messages), que chama a API interna com o mesmo contrato de marketingOptions.

2. Regras de produto que já protegem o remetente (antes do anti-spam “técnico”)

  • MARKETING e número da Pilot Status: não é permitido enviar MARKETING pelo número/instância padrão da Pilot Status; é preciso número próprio conectado. A API responde 403 com código TEMPLATE_CATEGORY_MARKETING_REQUIRES_OWN_NUMBER.
  • Opt-in e categorias: UTILITY exige opt-in do destino quando aplicável; MARKETING segue as regras de categoria do WhatsApp. Isso evita envio indevido e melhora reputação.
  • deliverUntil: para MARKETING, se não for informado, a plataforma define um prazo padrão de entrega (ordem de horas), após o qual a mensagem pode falhar se ainda não tiver sido concluída — útil para não “segurar” campanhas antigas indefinidamente.

3. Jitter humano na fila (timing “parece manual”)

Objetivo: espaçar envios na mesma instância (fluxo tenant + ambiente + instância) de forma menos previsível que um intervalo fixo.

Comportamento (resumo):

  • Random walk dentro da faixa configurável (padrão 8–25 s entre um envio e o próximo “slot”, via MARKETING_RANDOM_DELAY_MIN_MS / MARKETING_RANDOM_DELAY_MAX_MS).
  • Evita repetir o mesmo atraso consecutivo quando há mais de um valor possível.
  • Tende a quebrar sequências monótonas (subida ou descida contínua de delays).
  • A cada 5–8 mensagens (aleatório por ciclo), insere uma pausa longa (90–180 s), simulando “parar e voltar”.

Estado: guardado no Redis (chave versionada por tenant + ambiente + instância), com TTL renovado (ordem de 24 h) para fluxos inativos expirarem sozinhos.

Persistência / retomada: o worker grava no banco deliverBy e marca renderPlan.humanJitter.applied para não reaplicar o mesmo jitter em retry da mesma mensagem. Se o worker cair depois disso, ao voltar a mensagem segue a partir do deliverBy já persistido.

Redis indisponível (modo degradado):

  • O envio não para: usa jitter uniforme na mesma faixa min/max (stateSource degradado).
  • Há circuit breaker em memória para não martelar o Redis.
  • Alertas para equipe (Pushover), com throttle por fluxo (ex.: degradado ~10 min, recuperação ~30 min), para não gerar spam de alerta.

4. Batching irregular (micro-atraso entre mensagens)

Objetivo: acrescentar uma camada curta e irregular de espera depois do jitter humano e antes de renderizar/enviar, quebrando ainda mais o ritmo “metronomo” entre mensagens consecutivas no mesmo fluxo.

Padrão: atraso aleatório tipicamente entre 250 ms e 1,4 s (configurável por ambiente).

Persistência: idempotente via renderPlan.irregularBatch (applied, computedDelayMs, etc.), como o jitter humano.

Desligar: MARKETING_IRREGULAR_BATCH_ENABLED=0 (ver marketing-worker-anti-spam.md).

5. Variação de texto com IA (marketingOptions.aiRewriteEnabled)

Objetivo: quando o template é MARKETING e o cliente pede, o texto já renderizado (com variáveis substituídas) pode ser reescrito por IA para variar redação sem mudar intenção, números, URLs, nomes próprios e placeholders {{...}} que existirem no texto.

Onde ativar:

  • API: marketingOptions: { "aiRewriteEnabled": true } no corpo de POST /v1/messages/send (e equivalente na rota interna usada pelo dashboard).
  • UI: na tela de envio em massa, toggle de reescrita para templates MARKETING.

Limites de tamanho: a reescrita deve respeitar tolerância de comprimento em relação ao original (configurável via MARKETING_AI_REWRITE_LENGTH_TOLERANCE).

Se a IA falhar (indisponível, JSON inválido, etc.): o worker mantém o texto original e segue o envio; isso fica registrado nos traces de tentativa.

6. Guardrails de texto (quando a reescrita por IA está ativa)

Objetivo: evitar que uma variante “saia” parecendo cópia de envios recentes no mesmo fluxo (mesma instância), ou com padrão repetitivo demais.

Três verificações principais:

  1. Similaridade em relação a um histórico curto de textos já aceitos (armazenado no Redis para aquele fluxo).
  2. Repetição de bigramas (pares de palavras consecutivas em excesso).
  3. Diversidade lexical mínima (proporção de tokens únicos), para textos com tamanho mínimo de tokens.

Fluxo de decisão:

  1. Primeira reescrita (“standard”).
  2. Se os guardrails reprovarem, uma segunda reescrita com prompt mais estrito (“strict”).
  3. Se ainda reprovar, o worker usa o texto original renderizado e envia assim mesmo (campanha não trava).

Desligar guardrails: MARKETING_TEXT_GUARDRAILS_ENABLED=0. Limiares ajustáveis via variáveis MARKETING_GUARDRAIL_* (lista em marketing-worker-anti-spam.md).

Histórico: só entra texto aprovado após guardrails (evita poluir o histórico com variantes rejeitadas).

7. Como isso se combina na prática (disparo em massa)

| Camada | O que muda para o usuário final | |--------|----------------------------------| | Jitter humano + pausas longas | Menos “rajadas” iguais no tempo; ritmo mais humano na mesma instância. | | Micro-batch irregular | Pequenas variações extras entre uma mensagem e outra. | | IA + guardrails | Menos mensagens idênticas no texto; se a variante for ruim, cai no original. | | Várias instâncias | Cada instância tem sequência própria de jitter/histórico de guardrails — paralelizar números divide o comportamento temporal. |

Importante: paralelizar em várias instâncias reduz o tempo total agregado, mas cada número ainda segue suas próprias regras de fila e de histórico.

8. Observabilidade (para o time do tenant e suporte)

O worker grava eventos de trace (ex.: etapas marketing.human_jitter.applied, marketing.irregular_batch.applied, marketing.guardrails.summary, entradas/saídas de reescrita de IA). Isso ajuda a responder:

  • “Por que essa mensagem só saiu depois?” → deliverBy, pausa longa, micro-batch.
  • “Por que o texto voltou igual ao template?” → fallback de IA ou guardrails, motivo no trace.

9. Documentação relacionada na pasta docs/

| Documento | Conteúdo | |-----------|-----------| | marketing-worker-anti-spam.md | Variáveis de ambiente e toggles do worker. | | simulacao-anti-spam-100-mensagens-marketing.md | Exemplo de ordem de grandeza de duração de lote. | | api-publica-fluxo-envio-mensagem.md | Fluxo geral de envio pela API (se aplicável ao seu deploy). | | message-analisys/fluxo-envio-mensagens.md | Visão de fluxo de mensagens no sistema. |

10. O que a Pilot Status não substitui por você

As estratégias acima ajudam com padrão temporal e variação de texto técnica. Continuam essenciais:

  • Segmentação e frequência por contato (não insistir no mesmo destinatário).
  • Conteúdo alinhado à política do WhatsApp e opt-in.
  • Horários comerciais e expectativa do público.

Use este guia junto das boas práticas do seu time de marketing e compliance.