Meta CAPI delivery correctness for CTWA + landing WhatsApp: per-country dataset/WABA repointing and dual event_name by action_source

The Problem

The client runs two Meta WhatsApp campaign types: native Click-to-WhatsApp (CTWA) and ads-to-landing-page-with-WhatsApp-button. Conversions weren't optimizable: website Custom Conversions stayed empty, and an attempt to switch to standard events dead-lettered ~316 events in 30 minutes, blocking campaign scaling.

Approach & Architecture

Repointed each country's Meta destination to its per-country business-messaging dataset with the correct WhatsApp Business Account, then verified against the official Meta CAPI-for-Business-Messaging doc that business_messaging accepts LeadSubmitted/QualifiedLead/ViewContent but NOT 'Lead'. Designed a backwards-compatible dual event_name: business_messaging uses event_name (LeadSubmitted/QualifiedLead), website uses a new optional event_name_web (Lead/ViewContent), resolved per event by action_source. Also added optional page_url passthrough on the backend source so landing leads carry event_source_url. Gated entirely to the client via presence of event_name_web.

metaAdapter.resolveActionSource: ctwa_clid → business_messaging (messaging_channel=whatsapp, whatsapp_business_account_id, ctwa_clid unhashed); fbclid+page_url → website (event_source_url required); else configured/default. metaAdapter.resolveEventName picks event_name (messaging) or event_name_web (website, fallback to event_name). Delivery gate (deliver.ts) skips Meta events older than 7 days and events with no match key.

Key Decisions & Trade-offs

Hardest Part

Resolving the direct contradiction between Patagon's doc ('use Lead for CTWA') and a live Meta 2804066 rejection. Pulled Meta's official Conversions API for Business Messaging doc, which lists the exact accepted event set, 'Lead' is not in it, but LeadSubmitted/QualifiedLead/ViewContent are, settling it authoritatively and reframing the whole approach.

Technical Detail

Code

const actionSource = resolveActionSource(event, cfg);
const eventName = actionSource === 'business_messaging' ? cfg.event_name // LeadSubmitted / QualifiedLead : (cfg.event_name_web ?? cfg.event_name); // Lead / ViewContent (website)

const PLATFORM_MAX_EVENT_AGE_SECONDS = { meta: 7246060 };
if (maxAgeSec && isOlderThan(event.event_time, maxAgeSec, now())) { return { retry:false, status:'skipped', isSuccess:false }; // not dead-lettered
}

const lead = leads.find(l => l.ctwaClid);
const event = { source_event_name:'new_lead', event_id:lead.leadId+'diagctwa'+Date.now(), attribution:{ ctwa_clid: lead.ctwaClid } };
// expect submission.destinations[meta].destination_event_name === 'LeadSubmitted', status 'ok'

Measured Results

CTWA conversions deliver again as valid business-messaging events (LeadSubmitted/QualifiedLead, verified HTTP 200, no 2804066), and landing-page leads now also send website Lead/ViewContent that appear as selectable optimization events, unblocking the operator who could not switch an ad group off 'contact'. The dual-event change is gated to the client; a regression check confirmed no other client was affected.

Every figure above was recorded during the work itself. Where no number was measured, none is claimed.

Full Stack