Skip to main content
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:
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.