​

Futura campaign go-live testing

​

Scope

• audience definitions with all, tags, or segment targeting;
• typed custom-field filters for segment audiences;
• recipient materialization into campaign_recipients before dispatch;
• template binding by approved template name or template ID, locale, and body variables;
• normalized button reply IDs for campaign and journey routing;
• campaign-button opt-out events written to the consent ledger;
• deterministic route actions for contact tags, contact attributes, open conversations, and opt-outs.

​

Campaign metadata contract

{
  "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
  }
}

​

Preflight checklist

​

Materialize recipients

• reads the campaign audienceDefinition from v1 metadata;
• resolves all, tag, or segment audiences within the workspace;
• deduplicates contacts by ID;
• skips opted-out or unsubscribed contacts;
• inserts new queued recipients with a unique campaign_id,contact_id key;
• updates campaign metadata with materialization.materializedCount, skippedOptOutCount, duplicateCount, and materializedAt.

• materializedCount matches the approved count after consent skips;
• skippedOptOutCount is explainable and nonzero only when expected;
• a second materialization run reports duplicates instead of creating duplicate recipients;
• no campaign_recipients rows were created for contacts outside the workspace;
• no rows exist for known opted-out test contacts.

​

Dispatch and personalization checks

• a conversation exists or is created in the expected channel;
• an outbound messages row is queued with send_mode: template and author_label: Campaign;
• payload.templateName is the bound template name;
• payload.templateLocale is present when a locale is configured;
• payload.templateComponents includes body parameters in index order;
• contact.first_name resolves from contacts.metadata.first_name first, then from the first token of contacts.name, then to the configured fallback;
• the rendered message body preview replaces {{1}}, {{2}}, and later placeholders consistently with the template components;
• opted-out recipients encountered at dispatch are marked failed with error_code: skipped_opt_out and are not sent.

​

Button reply normalization

• legacy reply buttons: message.button.payload;
• interactive buttons: message.interactive.button_reply.id;
• interactive list replies: message.interactive.list_reply.id.

​

Consent opt-out test

1. Send a test campaign message to a consenting seed contact.
2. Reply by tapping the opt-out button, not by typing a STOP keyword.
3. Confirm a consent_events row is written with event_type: opted_out, source: campaign_button, actor: system, and metadata containing the buttonId and provider message ID.
4. Confirm the contact subscriber_status is updated to unsubscribed and the contact is no longer eligible for subsequent campaign materialization.
5. Confirm later dispatch attempts skip the contact before creating a Meta send.

​

Manual follow-up instead of campaign-started journeys

• futura_not_booked tags the contact, records futura_response=not_booked, and opens/routes the conversation to sales;
• a human operator reviews the conversation and sends the next approved reply manually;
• futura_already_booked tags or marks the contact as already booked and requires no automatic journey;
• marketing_opt_out records consent opt-out and must never trigger a marketing follow-up.

​

Operational go-live checklist

• Campaign metadata validates against v1 schema.
• Segment preview or tag count matches the signed-off audience.
• Typed custom-field filters were tested with at least one matching and one non-matching seed contact.
• Recipient materialization counts were recorded in launch notes.
• Approved template name, locale, and body-variable fallbacks were verified.
• Template component payloads were inspected for at least two seed contacts.
• Button IDs were tested from WhatsApp, not only from mocked webhook payloads.
• marketing_opt_out created a campaign_button consent ledger event.
• Post-opt-out materialization and dispatch both skipped the seed contact.
• Manual follow-up staffing is assigned for futura_not_booked and any optional futura_already_booked replies.
• Production route metadata contains no start_journey actions.
• campaign.dispatch and message.dispatch outbox jobs drained without unexpected failures.
• Delivery, read, failed, and skipped counts were compared with campaign detail metrics.
• Incident owner and rollback/pause decision point are documented.

​

Rollback and pause criteria

• materialization includes contacts outside the approved audience;
• opt-out contacts receive campaign messages;
• button replies are recorded as display labels instead of normalized IDs;
• launch planning depends on automatic campaign-to-journey start before BORD-431 is implemented;
• Meta returns sustained policy or template errors for the Futura template;
• delivery failures exceed the campaign owner’s agreed threshold.