Your AI Connector Docs

Atribuição de anúncios “Clique para o WhatsApp”

Se você executa anúncios “Clique para o WhatsApp” da Meta (Facebook/Instagram), o Your AI Connector pode informar de qual anúncio cada lead do WhatsApp veio — e fornecer o identificador de clique da Meta necessário para reportar conversões reais de volta à Meta. Isso permite que suas campanhas de anúncios sejam otimizadas para vendas e agendamentos reais, não apenas para “pessoas que iniciaram uma conversa.”

O que é capturado

Quando alguém toca em um anúncio “Clique para o WhatsApp” e envia uma mensagem para sua empresa, a Meta anexa informações ocultas de referência à primeira mensagem. O Your AI Connector as lê automaticamente e as armazena no contato. Sem configuração, sem ajustes — simplesmente acontece.

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

Campo O que é
ctwa_clid O identificador de clique da Meta. Este é o valor que você envia para a API de Conversões da Meta para atribuir uma conversão posterior ao clique exato no anúncio. Fica vazio para referências de postagens orgânicas (veja abaixo).
source_id O ID do anúncio (ou postagem) em que a pessoa clicou.
source_type Pode ser ad (um anúncio pago “Clique para o WhatsApp”) ou post (uma postagem orgânica no Facebook/Instagram).
source_url O link associado 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 pelo qual a referência chegou (atualmente sempre whatsapp).
captured_at Quando a referência foi registrada pela primeira vez no contato.

Você pode ver isso no painel de visualização rápida de um contato se tiver configurado um campo personalizado para ele, ou lê-lo diretamente por meio de webhooks e da API (veja abaixo) — ele não é exibido como seu próprio campo rotulado na tabela de Contatos.

Uma coisa que o payload não informa: em qual dos seus números a conversa chegou. Não há um id de página ou id de Conta do WhatsApp Business nele. Com um único número, isso não importa; se você utiliza vários números em diferentes Páginas do Facebook, precisará mapear isso do seu lado.

Em qual conexão isso funciona

Isso funciona apenas na conexão oficial da API do WhatsApp. A Meta entrega as informações estruturadas de referência (incluindo ctwa_clid) apenas através da API oficial do WhatsApp Business. A conexão não oficial do WhatsApp (web) não recebe isso — não há dados de clique de anúncio disponíveis nessa conexão, devido ao design de como ela funciona.

Portanto, se a atribuição de anúncios de ciclo fechado é importante para você, execute suas campanhas “Clique para o WhatsApp” usando um número conectado via API oficial do WhatsApp.

Comportamento de primeiro toque

A referência é capturada na primeira mensagem que um contato envia a partir de um anúncio. Se o mesmo contato clicar posteriormente em um anúncio diferente e esse novo clique contiver um identificador de clique, o ad_referral armazenado é atualizado para que o ID do clique permaneça atualizado para fins de relatório. Referências de postagens orgânicas (que não possuem ctwa_clid) nunca sobrescrevem um ID de clique de anúncio pago capturado anteriormente.

Enviando os dados para a Meta ou Google Ads

O Your AI Connector captura os dados de atribuição e os expõe, mas não envia conversões para a Meta ou Google nativamente para você hoje. Você encaminha os dados usando webhooks e uma ferramenta de automação.

O objeto ad_referral está incluído na seção contact dos eventos de webhook de saída (por exemplo, Nova Mensagem, Contato Retomado, Tags de Contato Atualizadas e eventos de análise, como Agendamento Confirmado).

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

  1. Um lead clica no seu anúncio “Clique para o WhatsApp” e envia uma mensagem. O Your AI Connector registra o ad_referral (incluindo o ctwa_clid) no contato.
  2. À medida que o lead avança — agendou uma chamada, tornou-se cliente, foi perdido — você marca esse resultado (veja “Carregando a etapa do funil” abaixo).
  3. Um webhook é disparado para sua ferramenta de automação (Zapier, Make ou Pabbly) contendo tanto o resultado quanto o ctwa_clid do contato.
  4. Sua ferramenta de automação chama a API de Conversões da Meta (usando o action_source = business_messaging e o ctwa_clid) ou o Google Ads (Importação de Conversões Offline / Conversões Aprimoradas para Leads) para reportar a conversão.

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

Levando o estágio do funil

Para relatar uma conversão, você geralmente precisa de duas coisas: o ID do clique (capturado automaticamente) e o resultado (que você define). A maneira mais confiável de anexar um resultado é com tags, porque a aplicação de uma tag dispara o webhook contact_tags_updated — e esse payload inclui o ad_referral do contato. (Remover uma tag não o dispara; veja Tags de Contato Atualizadas.)

Você pode aplicar tags automaticamente:

  • Deixe seu Agente de IA marcar o contato durante a conversa — configure regras de marcação automática na configuração do agente. É assim que o padrão “uma página de destino por anúncio → uma mensagem de entrada → uma tag” funciona se você quiser rotular a origem por conta própria.
  • Ou marque manualmente a partir de Chats ou da página de Contatos.

Sempre que uma tag relevante é alterada, o webhook é disparado com o ID do clique anexado, pronto para ser encaminhado como uma conversão.

A URL do webhook é definida na própria tag, na aba Tags do agente (ou campanha) ao qual o contato pertence — não nas Configurações. Cada tag recebe sua própria URL, e todas podem apontar para o mesmo endpoint se você quiser um único local para receber tudo.

Lendo um click id que você já perdeu

ad_referral também é retornado pela API tanto em GET /v1/contacts/{id} (como adReferral) quanto no endpoint de lista de contatos (como ad_referral), portanto, se o seu receptor estava fora do ar ou se você está conciliando dados posteriormente, você pode ler o click id de volta em vez de esperar pelo próximo webhook. Contatos que chegaram antes de o click id ser registrado neles possuem null aqui — o valor só pode ser capturado a partir da própria mensagem recebida, então não há nada a ser preenchido retroativamente.

Limitações

  • Apenas conexão oficial da API do WhatsApp (não a conexão web não oficial).
  • Ainda não há integração nativa de um clique com a Meta CAPI ou Google Ads — você encaminha os dados via Zapier/Make/Pabbly. Se você deseja uma integração nativa, informe o suporte em hi@youraiconnector.com.
  • A atribuição é capturada daqui para frente, a partir do momento em que isso estiver ativo. Ela não pode ser preenchida retroativamente em conversas que ocorreram antes.

Próximos passos