> ## 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

> Configure eventos de dry-run da API de Conversões do Meta Business Messaging para atribuição CTWA.

O Switchbord pode registrar eventos da Meta Business Messaging Conversions API para conversas Click-to-WhatsApp. O fluxo é intencionalmente centrado em registro (ledger-first) e desativado por padrão:

1. Uma referência entrante do WhatsApp captura `ctwa_clid` de `messages[].referral.ctwa_clid`.
2. O Switchbord armazena o id do clique no payload da mensagem entrante e em `conversation_attributions`.
3. As vinculações de dataset em nível de canal decidem se um evento `Lead`, `QuoteRequested` ou `Purchase` de CTWA é elegível.
4. Uma linha de registro em `meta_capi_events` é criada com um `event_id` determinístico.
5. O worker processa `meta.capi.dispatch` e envia para `/{dataset_id}/events` somente quando a vinculação está habilitada e não está em modo dry-run.

## Vinculação de dataset

As vinculações têm escopo de canal, não são globais. Use a rota de API do app abaixo a partir de um contexto autenticado de proprietário/administrador:

```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"]
  }'
```

Mantenha `dryRun=true` até que o Events Manager exiba eventos de teste com o formato de payload esperado. O despacho em produção (`dryRun=false`) é rejeitado a menos que um `testEventCode` esteja presente e a vinculação existente tenha sido marcada como verificada (`health_status='ok'` com `last_verified_at`).

## IDs de evento

O Switchbord usa ids determinísticos para deduplicação:

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

O banco de dados também aplica a restrição `unique (workspace_id, event_id)`.

## Regras de payload

Todo payload de despacho utiliza:

* `action_source: business_messaging`
* `messaging_channel: whatsapp`
* `partner_agent: switchbord`
* `user_data.ctwa_clid` quando disponível
* `user_data.page_id` quando configurado
* apenas telefone/id externo com hash; nunca armazene ou envie números de telefone em texto puro
* `custom_data.value` e `custom_data.currency` para o valor de cotação/compra, quando presente

Os tokens de acesso são sempre enviados no cabeçalho `Authorization: Bearer ***`, nunca como parâmetros de consulta na URL.

## Lançamento gradual (rollout)

1. Configure a vinculação com `enabled=true`, `dryRun=true` e um código de evento de teste.
2. Reproduza ou aguarde uma mensagem entrante de CTWA com `ctwa_clid`.
3. Confirme que `meta_capi_events.status = 'dry_run'` e que a pré-visualização do payload não contém token.
4. Envie eventos de teste no Events Manager.
5. Mude um canal para `dryRun=false` apenas para `Lead`.
6. Habilite `QuoteRequested` e `Purchase` somente após a verificação da integração com a fonte de verdade do Travio/status-3.

O rollback é instantâneo: defina `enabled=false` ou `dryRun=true` na vinculação do canal.