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”.

Está a publicar anúncios para uma página no seu próprio site com um botão de WhatsApp? Consulte Atribuição de cliques de anúncios para WhatsApp.

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 Conversions API da Meta para atribuir uma conversão a jusante ao clique exato no anúncio. 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 de Clique para o 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: whatsapp, instagram ou messenger.
captured_at Quando a referência foi registada pela primeira vez no contacto.

Pode vê-lo sem qualquer configuração: a página do contacto apresenta uma etiqueta Veio de um anúncio por baixo do nome (passe o rato por cima para ver os detalhes do anúncio), o painel de contacto junto à conversa também o mostra, e a Atividade do contacto começa com o toque no anúncio. Também pode lê-lo através de webhooks e da API (ver abaixo). Não é uma coluna 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.

Leads que chegam sem número de telefone

Algumas pessoas que lhe enviam mensagens a partir de um anúncio têm o seu número de telefone ocultado pelo WhatsApp. Nesse caso, a Meta fornece um ID privado da pessoa em vez de um número, e o contacto é criado com um campo de telefone vazio. Isso é esperado. As respostas, as respostas da IA e os seguimentos automáticos continuam a chegar à pessoa, porque o Your AI Connector comunica com ela através desse ID.

Deixe o campo de telefone vazio nesses contactos. Não introduza o seu próprio número de empresa: uma mensagem não pode ser enviada de um número para o próprio, pelo que o seguimento automático seguinte falharia e o contacto seria pausado. O Your AI Connector recusa agora guardar um dos seus próprios números ligados como telefone de um contacto. Se a pessoa partilhar o seu número mais tarde, ou lhe enviar uma mensagem novamente com o mesmo visível, este será preenchido automaticamente.

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.

Anúncios de Clique para o Instagram e Clique para o Messenger

Os anúncios que abrem uma mensagem direta (DM) do Instagram ou uma conversa no Messenger são registados da mesma forma, na página do Facebook e na conta do Instagram que ligou com o cartão Instagram & Messenger. Quando alguém inicia uma conversa a partir de um desses anúncios, o contacto recebe um ad_referral com channel definido como instagram ou messenger, source_type definido como ad e source_id definido como o ID do anúncio. Isto permite-lhe saber qual o anúncio por detrás de cada contacto, para que possa calcular o custo por reserva por anúncio.

Algumas diferenças em relação ao WhatsApp:

  • Não existe ctwa_clid; esse campo está vazio. A Meta apenas emite esse identificador de clique para o WhatsApp.
  • headline é o título do anúncio quando a Meta o envia, e source_url é a ligação para a imagem ou vídeo do anúncio, quando existe. body está vazio.
  • Se o contacto veio inicialmente de um anúncio e mais tarde inicia uma conversa a partir de um anúncio diferente, ad_referral mostra o anúncio mais recente.
  • Os contactos de anúncios do Messenger incluem o anúncio a partir de 14 de outubro de 2026. Os contactos que vieram de um anúncio do Messenger antes dessa data não têm ad_referral, porque os detalhes do anúncio não foram registados nessa altura e não podem ser preenchidos posteriormente.
  • As conversas do Messenger que começam com um toque no botão Começar da Página não são registadas. Remova o botão Começar da sua Página (Meta Business Suite, definições da Caixa de Entrada) para que as pessoas iniciem a conversa escrevendo, e o anúncio seja registado na sua primeira mensagem.

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

Your AI Connector captura os dados de atribuição e expõe-nos. Para anúncios que enviam pessoas primeiro para o seu próprio site, o Your AI Connector pode enviar resultados para a Meta por si quando uma etiqueta é aplicada: consulte Enviar resultados para a Meta. Para anúncios de clique para o WhatsApp, reencaminha 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 editor do agente de IA ao qual o contacto está atribuído, e não nas Definições. Cada etiqueta obtém o seu próprio URL e todas podem apontar para o mesmo endpoint, caso pretenda 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).
  • A funcionalidade integrada Enviar resultados para a Meta envia os dados de clique registados pelo script do site; não envia o ctwa_clid de anúncios de clique para o WhatsApp. Para esses, e para o Google Ads, reencaminha 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 entra em funcionamento. Não pode ser aplicada retroativamente a conversas que ocorreram anteriormente.

Próximos Passos