Skip to main content
Switchbord can record Meta Business Messaging Conversions API events for Click-to-WhatsApp conversations. The flow is intentionally ledger-first and disabled-by-default:
  1. A WhatsApp inbound referral captures ctwa_clid from messages[].referral.ctwa_clid.
  2. Switchbord stores the click id on the inbound message payload and conversation_attributions.
  3. Channel-level dataset bindings decide whether a CTWA Lead, QuoteRequested, or Purchase event is eligible.
  4. A meta_capi_events ledger row is created with a deterministic event_id.
  5. The worker processes meta.capi.dispatch and posts to /{dataset_id}/events only when the binding is enabled and not in dry-run mode.

​
Dataset binding

Bindings are channel scoped, not global. Use the app API route below from an authenticated owner/admin context:
Keep dryRun=true until Events Manager shows test events with the expected payload shape. Production dispatch (dryRun=false) is rejected unless a testEventCode is present and the existing binding has been marked verified (health_status='ok' with last_verified_at).

​
Event ids

Switchbord uses deterministic ids for deduplication:
  • Lead: meta-capi:lead:{workspaceId}:{conversationId}:{attributionId}
  • QuoteRequested: meta-capi:quote:{workspaceId}:{reservationTravioId}:{attributionId}
  • Purchase: meta-capi:purchase:{workspaceId}:{reservationTravioId}:{confirmationTimestamp}
The database also enforces unique (workspace_id, event_id).

​
Payload rules

Every dispatch payload uses:
  • action_source: business_messaging
  • messaging_channel: whatsapp
  • partner_agent: switchbord
  • user_data.ctwa_clid when available
  • user_data.page_id when configured
  • hashed phone/external id only; do not store or send raw phone numbers
  • custom_data.value and custom_data.currency for quote/purchase value when present
Access tokens are always sent in the Authorization: Bearer *** header, never as URL query parameters.

​
Rollout

  1. Configure binding with enabled=true, dryRun=true, and a test event code.
  2. Replay or wait for a CTWA inbound with ctwa_clid.
  3. Confirm meta_capi_events.status = 'dry_run' and payload preview has no token.
  4. Send Events Manager test events.
  5. Flip one channel to dryRun=false for Lead only.
  6. Enable QuoteRequested and Purchase only after Travio/status-3 source-of-truth integration is verified.
Rollback is instant: set enabled=false or dryRun=true on the channel binding.