Your AI Connector Docs

Atribuição de anúncios “Click-to-WhatsApp”

Se publica anúncios “Click to WhatsApp” na Meta (Facebook/Instagram), o Your AI Connector pode dizer-lhe de que anúncio veio cada lead do WhatsApp — e fornecer-lhe o identificador de clique da Meta de que necessita para comunicar conversões reais à Meta. Isto permite que as suas campanhas publicitárias sejam otimizadas para vendas e reservas reais, e não apenas para “pessoas que iniciaram uma conversa”.

O que é capturado

Quando alguém toca num anúncio “Click-to-WhatsApp” e envia uma mensagem à sua empresa, a Meta anexa informações de referência ocultas a essa primeira mensagem. O Your AI Connector lê-as automaticamente e guarda-as no contacto. Sem configuração, sem definições — acontece simplesmente.

As informações capturadas são armazenadas no contacto como ad_referral e contêm:

Campo O que é
ctwa_clid O identificador de clique da Meta. Este é o valor que envia para a API de Conversões da Meta para atribuir uma conversão a jusante ao clique exato no anúncio. Fica vazio para referências de publicações orgânicas (ver abaixo).
source_id O ID do anúncio (ou publicação) em que a pessoa clicou.
source_type Ou ad (um anúncio pago “Click-to-WhatsApp”) ou post (uma publicação orgânica do Facebook/Instagram).
source_url A ligação associada ao conteúdo do anúncio.
headline O texto do título do anúncio.
body O texto do corpo do anúncio.
channel O canal através do qual a referência chegou (atualmente sempre whatsapp).
captured_at Quando a referência foi registada pela primeira vez no contacto.

Pode ver isto no painel de visualização rápida de um contacto se tiver configurado um campo personalizado para o efeito, ou lê-lo diretamente através de webhooks e da API (ver abaixo) — não aparece como um campo próprio com etiqueta na tabela de Contactos.

Uma coisa que o payload não lhe diz: em qual dos seus números a conversa foi recebida. Não existe nenhum ID de página ou ID de Conta WhatsApp Business nele. Com um único número, isso não importa; se utilizar vários números em diferentes Páginas do Facebook, terá de mapear isso do seu lado.

Em que ligação funciona

Isto funciona apenas na ligação oficial da API do WhatsApp. A Meta apenas fornece as informações de referência estruturadas (incluindo ctwa_clid) através da API oficial do WhatsApp Business. A ligação não oficial do WhatsApp (web) não as recebe — não existem dados de cliques em anúncios disponíveis nessa ligação, devido à forma como esta funciona.

Portanto, se a atribuição de anúncios de ciclo fechado é importante para si, execute as suas campanhas “Click-to-WhatsApp” através de um número ligado via API oficial do WhatsApp.

Comportamento de primeiro contacto

A referência é capturada na primeira mensagem que um contacto envia a partir de um anúncio. Se o mesmo contacto clicar posteriormente num anúncio diferente e esse novo clique contiver um identificador de clique, o ad_referral armazenado é atualizado para que o ID de clique se mantenha atualizado para efeitos de relatório. As referências de publicações orgânicas (que não têm ctwa_clid) nunca substituem um ID de clique de anúncio pago capturado anteriormente.

Obter os dados para a Meta ou Google Ads

O Your AI Connector captura os dados de atribuição e expõe-nos, mas não envia conversões para a Meta ou Google de forma nativa atualmente. Deve encaminhar os dados utilizando webhooks e uma ferramenta de automatização.

O objeto ad_referral está incluído na secção contact dos eventos de webhook de saída (por exemplo, Nova Mensagem, Contacto Retomado, Etiquetas de Contacto Atualizadas e eventos de análise como Marcação de Reunião).

Uma configuração típica de ciclo fechado:

  1. Um lead clica no seu anúncio “Click-to-WhatsApp” e envia-lhe uma mensagem. O Your AI Connector regista o ad_referral (incluindo o ctwa_clid) no contacto.
  2. À medida que o lead progride — marcou uma chamada, tornou-se cliente, foi perdido — marca esse resultado (consulte “Carrying the funnel stage” abaixo).
  3. Um webhook é disparado para a sua ferramenta de automatização (Zapier, Make ou Pabbly) transportando tanto o resultado como o ctwa_clid do contacto.
  4. A sua ferramenta de automatização chama a Conversions API da Meta (utilizando o action_source = business_messaging e o ctwa_clid) ou o Google Ads (Importação de Conversões Offline / Conversões Avançadas para Leads) para comunicar a conversão.

Desta forma, a Meta e o Google aprendem quais os anúncios que produziram resultados reais e otimizam com base neles.

Transportar a fase do funil

Para comunicar uma conversão, normalmente precisa de duas coisas: o ID do clique (capturado automaticamente) e o resultado (que define). A forma mais fiável de associar um resultado é através de etiquetas, porque a aplicação de uma etiqueta dispara o webhook contact_tags_updated — e esse payload inclui o ad_referral do contacto. (Remover uma etiqueta não o dispara; consulte Contact Tags Updated.)

Pode aplicar etiquetas automaticamente:

  • Deixe o seu Agente de IA etiquetar o contacto durante a conversa — configure regras de etiquetagem automática na configuração do agente. É assim que funciona o padrão “uma página de destino por anúncio → uma mensagem de entrada → uma etiqueta”, caso pretenda identificar a origem manualmente.
  • Ou etiquete manualmente a partir das Conversas ou da página de Contactos.

Sempre que uma etiqueta relevante é alterada, o webhook é disparado com o ID do clique anexado, pronto a ser reencaminhado como uma conversão.

O URL do webhook é definido na própria etiqueta, no separador Etiquetas do agente (ou campanha) a que o contacto pertence — não nas Definições. Cada etiqueta obtém o seu próprio URL e todos podem apontar para o mesmo endpoint, se pretender um único local para receber tudo.

Ler um ID de clique que já perdeu

ad_referral é também devolvido pela API tanto em GET /v1/contacts/{id} (como adReferral) como no endpoint da lista de contactos (como ad_referral), por isso, se o seu recetor estiver em baixo, ou se estiver a reconciliar dados a posteriori, pode ler o ID de clique em vez de esperar pelo próximo webhook. Os contactos que chegaram antes de o ID de clique ter sido registado neles têm null aqui — o valor só pode ser capturado a partir da própria mensagem recebida, pelo que não há nada para preencher retroativamente.

Limitações

  • Apenas ligação oficial à API do WhatsApp (não a ligação web não oficial).
  • Ainda não existe integração nativa de um clique com a Meta CAPI ou Google Ads — encaminha os dados através do Zapier/Make/Pabbly. Se desejar uma integração nativa, informe o suporte em hi@youraiconnector.com.
  • A atribuição é capturada a partir do momento em que isto fica ativo. Não pode ser aplicada retroativamente a conversas que ocorreram anteriormente.

Próximos Passos