Integração com Meta CAPI e Google Offline Conversion ao mover de etapa

Anúncios digitais só ficam mais inteligentes quando recebem o sinal de conversão real. O SiteUp envia esse sinal automaticamente para Meta Conversions API e Google Ads Offline Conversion sempre que um card muda de etapa, desde que a integração esteja habilitada e o evento esteja mapeado. Este artigo descreve com precisão o mecanismo, quais identificadores são lidos e onde eles devem chegar.

Por que enviar conversões offline para os ad networks

Sem esse sinal, os algoritmos otimizam para clique e ficam cegos depois. Ao receber a conversão pós-funil, eles aprendem qual perfil realmente compra e o custo por aquisição cai com o tempo. A plataforma envia o evento no momento exato da mudança de etapa, com hash dos dados pessoais (SHA-256) e valor monetário, dentro dos requisitos das duas plataformas.

Onde os identificadores ficam armazenados

A precisão da atribuição depende de capturar o identificador certo no momento do clique e gravá-lo no lugar certo. A plataforma lê os identificadores da conversa e do contato:

conversation.custom_attributes.leadgen_id: ID do Lead Form nativo da Meta.
conversation.custom_attributes.ctwa_clid: clique de anúncio Click-to-WhatsApp.
conversation.custom_attributes.fbclid: clique de anúncio Meta para landing page.
conversation.custom_attributes.gclid: clique de anúncio Google Ads (também aceita gbraid e wbraid).
contact.additional_attributes.event_source_url ou landing_url: URL onde o lead converteu.
contact.additional_attributes.client_ip_address e client_user_agent: capturados no clique original.

Quando a integração é habilitada, o funil cria automaticamente os atributos personalizados de Conversa necessários (fbclid, ctwa_clid, leadgen_id para Meta CAPI; gclid, gbraid para Google Ads; e o conjunto utm_source, utm_medium, utm_campaign, utm_term, utm_content em ambos os casos). O processo é idempotente — só cria se ainda não existir.

Como o action_source é decidido (Meta CAPI)

O serviço escolhe o action_source em ordem de prioridade:

business_messaging se há ctwa_clid (Click-to-WhatsApp). Adiciona messaging_channel: whatsapp.
lead se há leadgen_id (Lead Form nativo Meta).
website se há fbclid (clique de anúncio para landing).
chat caso contrário (lead orgânico via WhatsApp).

O event_id é determinístico (kanban-<id>-<stage>-<event>) para deduplicar com o Pixel JS do site. Os dados pessoais (telefone E.164, e-mail lowercased, primeiro e último nome, contact_id) são enviados em hash SHA-256. Os tracking IDs (ctwa_clid, lead_id) são enviados sem hash. Quando o WABA ID está configurado, ele é incluído no user_data.

Como o gclid é enviado (Google Ads)

A integração com Google Ads usa Enhanced Conversions for Leads via API v20. Para cada conversão:

A plataforma faz refresh do access_token via OAuth com client_id, client_secret e refresh_token.
Monta a chamada :uploadClickConversions para customers/<customer_id>/conversionActions/<conversion_action_id>.
Envia gclid quando capturado e os identificadores hashedEmail e hashedPhoneNumber em SHA-256 como reforço/dedup.
Se send_value estiver ativo na configuração da etapa e o card tiver item_details.value, envia também conversionValue e currencyCode: BRL.

Telefones são normalizados para E.164 com prefixo BR (+55) quando faltar código de país.

Configuração por funil

Em funnel.settings.meta_capi (Meta CAPI):

enabled: liga a integração.
pixel_id e access_token: credenciais do Gerenciador de Eventos.
test_event_code: opcional, para testes no Events Manager.
inbox_ids: filtro opcional — só envia se a conversa pertencer a uma das inbox listadas.
waba_id: incluído no user_data para business_messaging.

Em funnel.settings.stage_events (Meta CAPI):

Mapa stage_key => { enabled, event_name } (ex.: Purchase, Lead, CompleteRegistration).

Em funnel.settings.google_ads (Google Ads):

enabled, customer_id e inbox_ids. Credenciais globais (developer_token, client_id, client_secret, refresh_token, login_customer_id) podem vir de variáveis de ambiente da instalação.

Em funnel.settings.google_ads_stage_events:

Mapa stage_key => { enabled, conversion_action_id, send_value }.

Quando o evento dispara

O envio acontece no callback after_commit do item, sempre que funnel_stage muda. A plataforma:

Verifica se a integração está ativa e se a etapa tem evento mapeado.
Avalia o filtro de inbox (se houver).
Monta o payload com os identificadores reais da conversa e do contato.
Faz a chamada HTTP com timeout de 10 s.
Registra o resultado em record_integration_event (status, HTTP code, etiqueta da etapa, erro se houver).
Faz broadcast integration.event_sent por ActionCable para o frontend mostrar o toast e adiciona uma entrada na timeline (activities) do card.

Para Meta CAPI, a plataforma trata events_received = 0 com HTTP 2xx como erro silencioso e o reporta na auditoria — Meta às vezes aceita o payload mas rejeita por validação. Para Google Ads, partialFailureError aparece como partial_failure.

Auditoria e reenvio

Cada envio fica registrado no card e no canal account_<id> em tempo real. Você pode acompanhar o histórico na timeline e investigar erros lendo as entradas com provider: meta_capi ou provider: google_ads. Movimentações erradas que dispararam evento podem exigir mover novamente a etapa com o conversion event corrigido — eventos já enviados respeitam a janela de atribuição de cada plataforma.

Boas práticas

Garanta a captura do click ID na origem: lead que chega sem fbclid, ctwa_clid, leadgen_id ou gclid perde a atribuição correta.
Padronize o value antes de mover para Ganho: o valor enviado é o que estiver no card no momento do callback.
Use test_event_code em sandbox: evita poluir os dados de produção.
Confira a taxa de match no Events Manager: hash com cobertura baixa indica falha na captura de e-mail/telefone.

Próximos passos

Para entender como configurar atributos do funil e etapas que disparam esses eventos, leia Criar funil e etapas e Movendo cards e automações. Para acompanhar o impacto, veja Métricas de conversão.