​

Testes de lançamento da campanha Futura

​

Escopo

• definições de audiência com direcionamento all, tags ou segment;
• filtros de campo customizado tipados para audiências de segmento;
• materialização de destinatários em campaign_recipients antes do disparo;
• vínculo de template por nome ou ID de template aprovado, locale e variáveis de corpo;
• IDs de resposta de botão normalizados para roteamento de campanha e journey;
• eventos de opt-out via botão de campanha gravados no ledger de consentimento;
• ações de rota determinísticas para tags de contato, atributos de contato, conversas abertas e opt-outs.

​

Contrato de metadados da campanha

{
  "audienceDefinition": {
    "kind": "tags",
    "tagIds": ["tag-vip"],
    "tagLabels": ["Futura"],
    "snapshotAt": "2026-04-27T07:00:00.000Z"
  },
  "templateBinding": {
    "templateName": "futura_repeat_guest_check_it",
    "locale": "it",
    "variables": [
      {
        "component": "body",
        "index": 0,
        "source": "contact.first_name",
        "fallback": "cliente"
      }
    ]
  },
  "responseRoutes": {
    "futura_not_booked": {
      "label": "Non ho ancora prenotato",
      "actions": [
        { "type": "tag_contact", "tagLabel": "futura_not_booked" },
        { "type": "open_conversation", "queue": "sales" },
        { "type": "set_contact_attribute", "attribute": "futura_response", "value": "not_booked" }
      ]
    },
    "futura_already_booked": {
      "label": "Ho già prenotato",
      "actions": [
        { "type": "tag_contact", "tagLabel": "futura_already_booked" },
        { "type": "set_contact_attribute", "attribute": "futura_response", "value": "already_booked" }
      ]
    },
    "marketing_opt_out": {
      "label": "Non voglio ricevere messaggi",
      "actions": [{ "type": "record_opt_out", "reason": "marketing_button" }]
    }
  },
  "launchSafety": {
    "requireDryRun": true,
    "maxRecipients": 500,
    "requireOptOutFooter": true
  }
}

​

Checklist de pré-voo

​

Materializar destinatários

• lê o audienceDefinition da campanha a partir dos metadados v1;
• resolve audiências all, de tag ou de segmento dentro do workspace;
• remove duplicidade de contatos por ID;
• ignora contatos com opt-out ou não inscritos;
• insere novos destinatários queued com uma chave única campaign_id,contact_id;
• atualiza os metadados da campanha com materialization.materializedCount, skippedOptOutCount, duplicateCount e materializedAt.

• materializedCount corresponde à contagem aprovada após os pulos de consentimento;
• skippedOptOutCount é explicável e diferente de zero apenas quando esperado;
• uma segunda execução de materialização reporta duplicados em vez de criar destinatários duplicados;
• nenhuma linha de campaign_recipients foi criada para contatos fora do workspace;
• não existem linhas para contatos de teste conhecidos com opt-out.

​

Verificações de disparo e personalização

• existe ou é criada uma conversa no canal esperado;
• uma linha de messages de saída é enfileirada com send_mode: template e author_label: Campaign;
• payload.templateName é o nome do template vinculado;
• payload.templateLocale está presente quando um locale é configurado;
• payload.templateComponents inclui os parâmetros de corpo na ordem dos índices;
• contact.first_name é resolvido primeiro a partir de contacts.metadata.first_name, depois do primeiro token de contacts.name, e só então do fallback configurado;
• a pré-visualização da mensagem renderizada substitui {{1}}, {{2}} e placeholders subsequentes de forma consistente com os componentes do template;
• destinatários com opt-out encontrados no disparo são marcados como falhos com error_code: skipped_opt_out e não são enviados.

​

Normalização de respostas de botão

• botões de resposta legados: message.button.payload;
• botões interativos: message.interactive.button_reply.id;
• respostas de lista interativa: message.interactive.list_reply.id.

​

Teste de opt-out de consentimento

1. Envie uma mensagem de teste de campanha para um contato de seed que tenha consentido.
2. Responda tocando no botão de opt-out, não digitando uma palavra-chave STOP.
3. Confirme que uma linha em consent_events é gravada com event_type: opted_out, source: campaign_button, actor: system e metadados contendo o buttonId e o ID da mensagem do provedor.
4. Confirme que o subscriber_status do contato é atualizado para unsubscribed e que o contato não é mais elegível para materializações subsequentes de campanha.
5. Confirme que tentativas de disparo posteriores ignoram o contato antes de criar um envio via Meta.

​

Acompanhamento manual em vez de journeys iniciadas por campanha

• futura_not_booked marca o contato com tag, registra futura_response=not_booked e abre/roteia a conversa para vendas;
• um operador humano revisa a conversa e envia manualmente a próxima resposta aprovada;
• futura_already_booked marca ou identifica o contato como já reservado e não requer journey automática;
• marketing_opt_out registra o opt-out de consentimento e nunca deve acionar um acompanhamento de marketing.

​

Checklist operacional de go-live

• Os metadados da campanha validam contra o schema v1.
• A pré-visualização do segmento ou a contagem de tags corresponde à audiência aprovada.
• Os filtros de campo customizado tipados foram testados com pelo menos um contato de seed correspondente e um não correspondente.
• As contagens de materialização de destinatários foram registradas nas notas de lançamento.
• O nome do template aprovado, o locale e os fallbacks de variável de corpo foram verificados.
• Os payloads de componente de template foram inspecionados para pelo menos dois contatos de seed.
• Os IDs de botão foram testados a partir do WhatsApp, não apenas de payloads de webhook mockados.
• marketing_opt_out criou um evento no ledger de consentimento campaign_button.
• A materialização e o disparo pós-opt-out ambos ignoraram o contato de seed.
• A equipe de acompanhamento manual está designada para futura_not_booked e quaisquer respostas opcionais de futura_already_booked.
• Os metadados de rota de produção não contêm ações start_journey.
• Os jobs de outbox campaign.dispatch e message.dispatch foram esvaziados sem falhas inesperadas.
• As contagens de entrega, leitura, falha e pulo foram comparadas com as métricas de detalhe da campanha.
• O responsável pelo incidente e o ponto de decisão de rollback/pausa estão documentados.

​

Critérios de rollback e pausa

• a materialização inclui contatos fora da audiência aprovada;
• contatos com opt-out recebem mensagens de campanha;
• respostas de botão são registradas como rótulos de exibição em vez de IDs normalizados;
• o planejamento de lançamento depende de início automático de campanha para journey antes de o BORD-431 estar implementado;
• a Meta retorna erros sustentados de política ou de template para o template Futura;
• as falhas de entrega excedem o limite acordado pelo responsável pela campanha.