Atribuição de cliques em anúncios para WhatsApp #

Se você veicula anúncios no Meta ou Google para uma página em seu próprio site, e essa página possui um botão do WhatsApp, o Your AI Connector pode lhe dizer de qual clique no anúncio veio cada conversa no WhatsApp. Você cola um pequeno script em seu site. Quando um visitante toca no seu botão do WhatsApp, o clique é memorizado e associado à primeira mensagem que ele lhe envia. O contato então mostra a campanha de onde veio, e os dados do clique acompanham o contato em webhooks, na API e, se desejar, de volta ao Meta.

Isso funciona para qualquer página com um botão do WhatsApp: uma landing page, uma página de agendamento, uma página de preços ou um quiz que termina em “Enviar minhas respostas pelo WhatsApp”.

Esta página trata de anúncios que enviam pessoas primeiro para o seu site. Se seus anúncios abrem o WhatsApp diretamente (anúncios “Clique para o WhatsApp” do Meta), isso é coberto automaticamente, sem um script, em Atribuição de anúncios Clique para o WhatsApp.

Configuração #

1. Vá para Configurações → Rastreamento de cliques em anúncios (grupo Integrações).
2. Clique em Ativar e obter meu script. Sua conta recebe sua própria chave de site e um script de uma linha.
3. Copie o script e cole-o logo antes da tag de fechamento </body> em todas as páginas que possuem um botão do WhatsApp:

<script src="https://api.youraiconnector.com/v1/ad-visit/YOUR_SITE_KEY.js" async></script>

4. Opcional: em Número do WhatsApp, digite o número para o qual seus botões direcionam. Apenas links para esse número serão rastreados. Deixe vazio para rastrear todos os links do WhatsApp no site.
5. Escolha a redação do número de consulta (veja abaixo) e clique em Salvar. Você não precisa alterar o script em seu site após uma alteração nas configurações.
6. Teste: abra sua página a partir de um link com uma tag de campanha, por exemplo https://yoursite.com/?utm_source=test&utm_campaign=setup-check, toque no seu próprio botão do WhatsApp e envie a mensagem. Abra esse contato em Chats: o painel de contato mostrará Veio de um clique em anúncio com a campanha.

A chave do site já está dentro do script. Não é uma senha, portanto, não há problema em estar em uma página pública.

O que o script faz #

• Quando a página carrega, ele mantém os IDs de clique de anúncio e tags de campanha (os parâmetros utm_) do endereço da página no armazenamento de sessão da aba do navegador, para que ainda estejam lá se o visitante olhar outra página primeiro. Ele não define cookies, não carrega mais nada e não envia nada.
• Quando o visitante toca em um link do WhatsApp (wa.me, api.whatsapp.com/send ou whatsapp://send), ele adiciona o número de consulta à mensagem, registra a visita e permite que o toque continue para o WhatsApp normalmente.

Nada é enviado para o Your AI Connector antes do toque.

O número de consulta #

Um número curto, como a referência que uma loja ou clínica lhe dá, é adicionado à mensagem de WhatsApp do visitante. É assim que o Your AI Connector sabe exatamente qual clique de anúncio pertence a qual conversa. Uma mensagem tem esta aparência:

Hi, I would like to know more.
Enquiry no. 4827

• Redação: “Nº da consulta” é o padrão. Você pode usar qualquer linha de texto que soe natural para o seu negócio, como “Ref. de agendamento” ou “Ref.”. Sem dígitos.
• Onde: Em sua própria última linha (o padrão) ou No final do texto. A página de configurações mostra uma prévia ao vivo.
• Comprimento: 4 dígitos, ou 5 quando seu site estiver muito movimentado.
• Seu agente de IA nunca o vê e nunca o repete. A caixa de entrada mostra a mensagem completa, incluindo o número.

Você pode desativar o número de consulta. A correspondência então funciona apenas com base no texto da mensagem, portanto, dois visitantes que enviam exatamente o mesmo texto (por exemplo, as mesmas respostas de um quiz) não podem ser diferenciados, e alguns cliques não serão correspondidos.

Seu próprio código de quiz ou botão #

Se a sua página cria a mensagem do WhatsApp por conta própria (um quiz que coloca as respostas no texto, ou seu próprio código de botão), adicione data-manual à tag script:

<script src="https://api.youraiconnector.com/v1/ad-visit/YOUR_SITE_KEY.js" data-manual async></script>

Com data-manual, o script não altera mais os links do WhatsApp por conta própria. Seu próprio código o chama logo antes de abrir o WhatsApp, para que cada visita seja registrada uma vez:

• window.ChatAttribution.text(finalText, number) retorna seu texto com o número de consulta adicionado e registra a visita. Use o texto retornado no seu link do WhatsApp.
• window.ChatAttribution.link(finalText, number) faz o mesmo e retorna um link wa.me pronto com esse texto. Omita o número para usar aquele que está em Número do WhatsApp nas configurações.

<script>
  function sendAnswers(answers) {
    var text = "Hi, my answers: " + answers.join(", ");
    if (window.ChatAttribution) {
      window.location.href = window.ChatAttribution.link(text, "+15551234567");
    } else {
      window.location.href = "https://wa.me/15551234567?text=" + encodeURIComponent(text);
    }
  }
</script>

A ramificação else mantém o botão funcionando caso o script não tenha sido carregado, por exemplo, quando uma extensão de navegador o bloqueia. Um texto que já contém um número emitido pelo script nunca é alterado uma segunda vez.

O que é registrado #

No momento do toque, o registro da visita contém:

• os IDs de clique de anúncio no endereço da página, como fbclid (Meta) e gclid (Google)
• os cookies _fbc e _fbp, se o seu próprio pixel da Meta os definiu em seu site (o script os lê, ele nunca os define)
• as tags de campanha (utm_source, utm_medium, utm_campaign, utm_content, utm_term)
• a página de destino, a página de onde o visitante veio, o navegador e o texto da mensagem
• o endereço IP e o horário, adicionados pelo Your AI Connector quando a visita chega

Quando uma visita é correspondida, o Your AI Connector também calcula a partir desses dados aproximadamente onde o visitante estava (cidade e país, de forma aproximada, a partir do endereço IP) e qual dispositivo ele usou (celular, tablet ou computador, o sistema operacional e o navegador, por exemplo, o navegador interno do Instagram). A localização permanece vazia quando não pode ser calculada, o que é comum em redes móveis.

Os registros de visita são mantidos por 90 dias. Quando uma visita é correspondida, uma cópia dos seus dados de clique é armazenada no contato e permanece com ele até que você a exclua.

Seu aviso de privacidade: o script é executado no seu site, portanto, o aviso de privacidade do seu site deve mencioná-lo: o que ele registra (a lista acima) e que ele faz isso quando um visitante toca em um botão do WhatsApp.

Como a correspondência funciona #

Quando a primeira mensagem de um contato chega, o Your AI Connector procura por uma visita nos 15 minutos anteriores:

1. Primeiro pelo número de consulta. Uma mensagem que contém um número emitido pelo script é correspondida a essa visita.
2. Caso contrário, pelo texto idêntico. Uma mensagem com exatamente o mesmo texto que uma visita é correspondida a ela. Quando dois visitantes diferentes enviam o mesmo texto dentro do intervalo, nenhum dos dois é correspondido, propositalmente, para que um contato nunca seja atribuído ao anúncio errado.

Uma mensagem posterior que contenha o número de consulta também é correspondida, desde que o contato ainda não tenha uma correspondência.

Quando um contato que já possui uma correspondência retorna por meio de outro anúncio e envia uma mensagem contendo um número de consulta mais recente, esse clique é mantido como o clique mais recente do contato. A primeira correspondência permanece como está.

• Primeiro clique, para seus relatórios: o contato continua mostrando de onde o lead veio originalmente. Isso nunca muda.
• Clique mais recente, para a Meta: eventos enviados para a Meta usam o clique mais novo, porque a Meta credita o anúncio que trouxe a pessoa de volta e apenas dentro de sua janela de atribuição. Reportar um clique antigo creditaria o anúncio errado, ou nenhum.
• O clique mais recente é obtido apenas a partir de um número de consulta, nunca apenas pela correspondência de texto, e uma visita mais antiga nunca substitui uma mais recente.

Limites:

• A primeira correspondência nunca é sobrescrita. Cliques mais recentes vão para o clique mais recente.
• Apenas WhatsApp: os canais WhatsApp Business API e WhatsApp Web.
• 15 minutos: um visitante que toca no botão, mas envia a mensagem muito tempo depois, não é correspondido.
• Apenas daqui para frente: contatos de antes de você instalar o script não possuem correspondência.

Onde você vê isso #

• Painel de contato: Veio de um clique em anúncio com a campanha ou origem e a data do primeiro clique. Passe o mouse para ver os detalhes: a campanha, o Anúncio (utm_content) e o Conjunto de anúncios (utm_term), a Localização aproximada e o Dispositivo, cada um apenas quando conhecido, além do mesmo para o clique mais recente, quando houver. Tags de campanha que nunca foram preenchidas (um toque na prévia do anúncio envia o modelo da tag em vez dos nomes) são omitidas. Uma visita só conta como um clique em anúncio quando a página foi aberta a partir de um link de anúncio (um ID de clique da Meta ou do Google, ou tags de campanha). Qualquer pessoa que tenha chegado à página de outra forma, por exemplo, via pesquisa do Google, digitando seu endereço ou clicando em seu site, mostrará Veio do seu site com a origem, como Pesquisa do Google, ou Visita ao site, nenhum referenciador registrado quando o navegador não informou.
• Página de contato: a mesma linha aparece abaixo do nome do contato em Contatos, para que você veja imediatamente, inclusive no seu celular. Passe o mouse ou toque para ver os detalhes.
• Atividade: a linha do tempo do contato começa com Tocou no seu botão do WhatsApp após um anúncio (ou em seu site) no momento do clique, antes da primeira mensagem. O painel de contato do chat mostra a mesma linha em Atividade.
• Webhooks: contact.ad_attribution em webhooks de tag de agente e em cada evento de assinatura de webhook que carrega um contato.
• API: ad_attribution na lista de contatos e adAttribution em um contato individual, na seção Contatos da referência da API.
• Ferramentas MCP: o mesmo objeto em cada contato que elas retornam.

O valor é null quando o contato não possui correspondência. Os campos abaixo descrevem o primeiro clique. Quando um clique posterior é correspondido, latest o armazena com os mesmos campos; ele fica ausente até esse momento.

Enviar resultados para a Meta (opcional) #

Você pode permitir que o Your AI Connector relate resultados de volta para sua conta de anúncios da Meta, para que a Meta aprenda quais anúncios trazem leads e vendas reais e otimize com base neles. Isso utiliza seus próprios detalhes da Conversions API da Meta.

1. No Gerenciador de Eventos da Meta, encontre o ID do seu pixel (também chamado de conjunto de dados) em Fontes de dados e crie um token de acesso em Configurações, Conversions API, Gerar token de acesso.
2. Em Configurações → Rastreamento de cliques em anúncios, em Enviar resultados para a Meta (opcional), insira o ID do pixel / conjunto de dados e o Token de acesso. Clique em Salvar detalhes da Meta.
3. Opcional: verifique a conexão. No Gerenciador de Eventos da Meta, abra seu pixel e vá para a aba Testar eventos, copie o código de teste exibido lá, cole-o em Enviar um evento de teste e clique em Enviar evento de teste. A linha abaixo do botão dirá “A Meta recebeu 1 evento de teste” (procure por isso em Testar eventos na Meta) ou mostrará o motivo da recusa pela Meta, por exemplo, um token incorreto. O código é usado apenas para esse teste e nunca é salvo.
4. Abra o editor de agentes, vá para a aba Tags e abra uma tag. Em Enviar para a Meta, escolha o evento: Lead, Contato, Agendamento, Compra ou um nome personalizado. Opcionalmente, adicione um valor e uma moeda.

A partir de então, sempre que essa tag for aplicada a um contato (pela IA, manualmente, via API ou por uma automação), o Your AI Connector envia o evento para a Meta com os dados do clique mais recente do contato (fbc, fbp, endereço IP, navegador, página de destino, a partir do clique mais recente quando houver um, caso contrário, o primeiro) mais seu telefone, e-mail e nome, com hash, para que a Meta possa vinculá-lo ao anúncio. Um contato sem correspondência ainda envia o evento, apenas com o telefone, e-mail e nome com hash.

• Eventos ao vivo contam sempre: um código de evento de teste nunca é armazenado com seus detalhes da Meta, portanto, os eventos que suas tags e automações enviam sempre vão para seus dados reais na Meta, nunca para a aba Testar eventos.
• Sem contagem dupla: cada evento tem um ID fixo composto pelo ID do contato e pelo nome da tag. Se seu CRM enviar o mesmo evento para a Meta com o mesmo ID, a Meta manterá apenas um.
• Janela de atribuição da Meta: a Meta só credita um evento a um anúncio dentro de sua janela de atribuição, que é de 7 dias após o clique por padrão. Um negócio que é fechado semanas depois não contará por si só, portanto, envie também um evento anterior, por exemplo, uma tag para a consulta agendada ou paga.

Enviar conversões a partir de automações #

Uma tag envia seu evento quando é aplicada. Quando o resultado ocorre em outro lugar, como o fechamento de um negócio no seu CRM ou o agendamento de uma consulta, use a ação Enviar conversão para o Meta em uma automação. Ela reporta um evento para o seu conjunto de dados (dataset) do Meta através da Conversions API, para que o Meta otimize seus anúncios com base em resultados reais e não apenas em mensagens.

Ela utiliza os mesmos detalhes do Meta que as tags: o ID do Pixel / conjunto de dados e o Token de acesso em Configurações → Rastreamento de cliques em anúncios. Sem eles, a etapa falha com a mensagem “Meta não está conectado”.

Os campos

Preencha pelo menos um entre Contato, E-mail ou Telefone. A pessoa não precisa ser um contato: um negócio no HubSpot que atinge o status “Fechado e Ganho” pode enviar uma “Compra” com o valor do negócio e o e-mail do comprador.

Ao selecionar um Contato, o telefone, e-mail e nome dele são usados. Se eles vieram de um clique em anúncio que o script identificou, os detalhes do clique também são enviados, o que ajuda o Meta a associar o evento ao anúncio. E-mail, telefone e nomes são hashados antes de serem enviados. O ID do clique, endereço IP e navegador são enviados conforme exigido pelo Meta.

ID do evento e contagem dupla

O Meta contabiliza eventos com o mesmo nome de evento e o mesmo ID de evento apenas uma vez. Use um ID fixo, como o ID do negócio, quando outra ferramenta também reportar a mesma conversão ou quando a automação puder ser executada duas vezes para o mesmo item. Deixe vazio para que um novo ID seja criado a cada execução, fazendo com que cada execução seja contabilizada.

Como difere dos eventos de tag

O evento Enviar para o Meta de uma tag é disparado uma vez por contato para aquela tag (no máximo uma vez a cada 30 dias). Esta ação envia toda vez que é executada. O ID do evento é o que impede que uma conversão seja contabilizada duas vezes.

Exemplo: um negócio fechado e uma consulta agendada

1. Inicie uma automação que seja executada quando um negócio for ganho: um gatilho de Evento de aplicativo no evento de negócio do seu CRM, com uma Condição para que apenas negócios ganhos prossigam. O HubSpot envia eventos de estágio de negócio apenas para aplicativos de desenvolvedor, portanto, para o HubSpot, use um gatilho de Agendamento com uma pesquisa do HubSpot para negócios que atingiram o status Fechado/Ganho desde a última execução, e um Loop sobre eles.
2. Adicione Enviar conversão para a Meta. Defina o Nome do evento como Compra, o Valor como o valor do negócio (insira-o com o botão +) e a Moeda como a sua moeda. Coloque o e-mail do comprador em E-mail e o ID do negócio em ID do evento, para que o mesmo negócio nunca seja contabilizado duas vezes.
3. Para uma consulta agendada, inicie uma segunda automação com o gatilho Consulta agendada e adicione Enviar conversão para a Meta com o Nome do evento definido como Agendamento e o contato do gatilho em Contato. Se desejar, adicione uma segunda etapa de Enviar conversão para a Meta que envie uma Compra com um valor fixo, como o preço da consulta.

Você também pode enviar uma conversão via API com POST https://api.youraiconnector.com/v1/ad-attribution/meta-event. Ela aceita os mesmos campos em formato snake case: event_name, value, currency, contact_id, email, phone, first_name, last_name, external_id, event_id, event_time, event_source_url e test_event_code.

Perguntas frequentes #

Isso funciona se meu anúncio abrir o WhatsApp diretamente? Esses anúncios não passam pelo seu site, então o script nunca é executado. A Meta envia os detalhes do anúncio com a primeira mensagem, veja Atribuição de Anúncios Click-to-WhatsApp.

O script deixa meu site lento ou define cookies? Ele carrega em segundo plano (async), não define cookies e não carrega nada mais. Ele só envia algo quando um visitante toca em um botão do WhatsApp.

Posso rastrear o Google Ads além dos anúncios da Meta? Sim. IDs de clique do Google (gclid, gbraid, wbraid) e quaisquer tags de campanha são registrados e exibidos no contato. O envio de resultados de volta está disponível apenas para a Meta.

Por que um contato não obteve uma correspondência? Os motivos mais comuns: a mensagem chegou mais de 15 minutos após o toque, o número da consulta foi removido da mensagem, o número da consulta está desativado e outro visitante enviou o mesmo texto, ou a página não possui o script.

Meu site tem links para dois números de WhatsApp. Posso rastrear apenas um? Sim. Digite esse número em Número do WhatsApp nas configurações. Deixe vazio para rastrear todos os links do WhatsApp.

Posso alterar o texto mais tarde? Sim. As alterações são aplicadas ao seu site imediatamente; você não precisa colar o script novamente.