> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Business Messaging CAPI

> Configurare eventi Meta Business Messaging Conversions API in modalità dry-run per l'attribuzione CTWA.

Switchbord può registrare eventi della Meta Business Messaging Conversions API per le conversazioni Click-to-WhatsApp. Il flusso è intenzionalmente ledger-first e disabilitato di default:

1. Un referral WhatsApp in entrata acquisisce `ctwa_clid` da `messages[].referral.ctwa_clid`.
2. Switchbord memorizza il click id sul payload del messaggio in entrata e su `conversation_attributions`.
3. I binding del dataset a livello di canale determinano se un evento CTWA `Lead`, `QuoteRequested`, o `Purchase` è idoneo.
4. Viene creata una riga nel ledger `meta_capi_events` con un `event_id` deterministico.
5. Il worker elabora `meta.capi.dispatch` e invia a `/{dataset_id}/events` solo quando il binding è attivato e non in modalità dry-run.

## Binding del dataset

I binding sono ambito canale, non globali. Usa la route API dell'app riportata sotto da un contesto autenticato owner/admin:

```bash theme={null}
curl -X POST \
  /api/settings/channels/<channel-id>/meta-capi-binding \
  -H 'content-type: application/json' \
  -d '{
    "datasetId": "<events-manager-dataset-id>",
    "pageId": "<optional-page-id>",
    "enabled": true,
    "dryRun": true,
    "testEventCode": "TEST123",
    "allowedEventNames": ["Lead"]
  }'
```

Mantieni `dryRun=true` finché Events Manager non mostra eventi di test con la forma del payload attesa. L'invio in produzione (`dryRun=false`) viene rifiutato a meno che non sia presente un `testEventCode` e il binding esistente sia stato contrassegnato come verificato (`health_status='ok'` con `last_verified_at`).

## ID evento

Switchbord usa ID deterministici per la deduplicazione:

* `Lead`: `meta-capi:lead:{workspaceId}:{conversationId}:{attributionId}`
* `QuoteRequested`: `meta-capi:quote:{workspaceId}:{reservationTravioId}:{attributionId}`
* `Purchase`: `meta-capi:purchase:{workspaceId}:{reservationTravioId}:{confirmationTimestamp}`

Il database applica inoltre il vincolo `unique (workspace_id, event_id)`.

## Regole del payload

Ogni payload di dispatch usa:

* `action_source: business_messaging`
* `messaging_channel: whatsapp`
* `partner_agent: switchbord`
* `user_data.ctwa_clid` quando disponibile
* `user_data.page_id` quando configurato
* solo id di telefono/esterno con hash; non memorizzare né inviare numeri di telefono in chiaro
* `custom_data.value` e `custom_data.currency` per il valore di quote/purchase quando presente

I token di accesso vengono sempre inviati nell'header `Authorization: Bearer ***`, mai come parametri di query nell'URL.

## Rollout

1. Configura il binding con `enabled=true`, `dryRun=true`, e un codice di evento di test.
2. Riproduci o attendi un inbound CTWA con `ctwa_clid`.
3. Conferma che `meta_capi_events.status = 'dry_run'` e che l'anteprima del payload non contenga il token.
4. Invia eventi di test a Events Manager.
5. Passa un canale a `dryRun=false` solo per `Lead`.
6. Attiva `QuoteRequested` e `Purchase` solo dopo che l'integrazione con la fonte di verità Travio/status-3 è stata verificata.

Il rollback è istantaneo: imposta `enabled=false` oppure `dryRun=true` sul binding del canale.