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

Se publica anúncios na Meta ou no Google para uma página do seu próprio site, e essa página tem um botão de WhatsApp, o Your AI Connector pode dizer-lhe de que clique em anúncio veio cada conversa de WhatsApp. Basta colar um pequeno script no seu site. Quando um visitante toca no seu botão de WhatsApp, o clique é memorizado e associado à primeira mensagem que lhe enviam. O contacto mostra então a campanha de que provém, e os dados do clique seguem com o contacto para webhooks, para a API e, se desejar, de volta para a Meta.

Isto funciona para qualquer página com um botão de WhatsApp: uma landing page, uma página de marcações, uma página de preços ou um questionário que termina em “Enviar as minhas respostas por WhatsApp”.

Esta página é sobre anúncios que enviam as pessoas primeiro para o seu site. Se os seus anúncios abrem o WhatsApp diretamente (anúncios “Click to WhatsApp” da Meta), isso é coberto automaticamente, sem necessidade de script, em Atribuição de anúncios Click-to-WhatsApp.

Configuração #

1. Vá a Definições → Rastreio de cliques em anúncios (grupo Integrações).
2. Clique em Ativar e obter o meu script. A sua conta recebe a sua própria chave de site e um script de uma linha.
3. Copie o script e cole-o imediatamente antes da tag de fecho </body> em todas as páginas que tenham um botão de WhatsApp:

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

4. Opcional: em Número de WhatsApp, escreva o número para o qual os seus botões apontam. Apenas as ligações para esse número serão então rastreadas. Deixe em branco para rastrear todas as ligações de WhatsApp no site.
5. Escolha a redação do número de consulta (ver abaixo) e clique em Guardar. Não precisa de alterar o script no seu site após uma alteração nas definições.
6. Teste: abra a sua página a partir de uma ligação com uma tag de campanha, por exemplo https://yoursite.com/?utm_source=test&utm_campaign=setup-check, toque no seu próprio botão de WhatsApp e envie a mensagem. Abra esse contacto em Conversas: o painel de contacto mostra Veio de um clique em anúncio com a campanha.

A chave do site já está dentro do script. Não é uma palavra-passe, por isso não há problema em estar numa página pública.

O que o script faz #

• Quando a página carrega, mantém os IDs de clique de anúncio e as tags de campanha (os parâmetros utm_) do endereço da página no armazenamento de sessão do separador do navegador, para que ainda lá estejam caso o visitante veja outra página primeiro. Não define cookies, não carrega mais nada e não envia nada.
• Quando o visitante toca numa ligação de WhatsApp (wa.me, api.whatsapp.com/send ou whatsapp://send), adiciona o número de consulta à mensagem, regista 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 que clique em anúncio pertence a que conversa. Uma mensagem tem este aspeto:

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

• Redação: “N.º de consulta” é a predefinição. Pode usar qualquer linha de texto que soe natural para o seu negócio, como “Ref. de marcação” ou “Ref.”. Sem dígitos.
• Onde: Na sua própria última linha (a predefinição) ou No final do texto. A página de definições mostra uma pré-visualização em tempo real.
• Comprimento: 4 dígitos, ou 5 quando o seu site tem muito tráfego.
• O seu agente de IA nunca o vê e nunca o repete. A caixa de entrada mostra a mensagem completa, incluindo o número.

Pode desativar o número de pedido. A correspondência passa a funcionar apenas com base no texto da mensagem, pelo que dois visitantes que enviem exatamente o mesmo texto (por exemplo, as mesmas respostas a um questionário) não podem ser distinguidos e alguns cliques não serão correspondidos.

O seu próprio código de questionário ou botão #

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

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

Com data-manual, o script deixa de alterar os links do WhatsApp automaticamente. O seu próprio código chama-o imediatamente antes de abrir o WhatsApp, para que cada visita seja registada uma vez:

• window.ChatAttribution.text(finalText, number) devolve o seu texto com o número de pedido adicionado e regista a visita. Utilize o texto devolvido no seu link de WhatsApp.
• window.ChatAttribution.link(finalText, number) faz o mesmo e devolve um link wa.me pronto com esse texto. Omita o número para utilizar o que se encontra em Número de WhatsApp nas definiçõ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 a funcionar caso o script não tenha sido carregado, por exemplo, quando uma extensão do navegador o bloqueia. Um texto que já contenha um número emitido pelo script nunca é alterado uma segunda vez.

O que é registado #

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

• os IDs de clique de anúncio no endereço da página, tais como fbclid (Meta) e gclid (Google)
• os cookies _fbc e _fbp, se o seu próprio pixel da Meta os tiver definido no seu site (o script lê-os, nunca os define)
• as etiquetas 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 a hora, 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 que dispositivo utilizou (telemóvel, tablet ou computador, o sistema operativo e o navegador, por exemplo, o navegador integrado do Instagram). A localização permanece vazia quando não é possível determiná-la, o que é comum em redes móveis.

Os registos de visitas são mantidos durante 90 dias. Quando uma visita é correspondida, uma cópia dos seus dados de clique é armazenada no contacto e permanece com o contacto até que a elimine.

A sua política de privacidade: o script é executado no seu site, pelo que a política de privacidade do seu site deve mencioná-lo: o que regista (a lista acima) e que o faz quando um visitante toca num botão de WhatsApp.

Como funciona a correspondência #

Quando chega a primeira mensagem de um contacto, o Your AI Connector procura uma visita dos 15 minutos anteriores:

1. Primeiro pelo número de pedido. Uma mensagem que contenha um número emitido pelo script é correspondida a essa visita.
2. Caso contrário, por texto idêntico. Uma mensagem com exatamente o mesmo texto que uma visita é correspondida a essa mesma. Quando dois visitantes diferentes enviam o mesmo texto dentro do intervalo de tempo, nenhum é correspondido, propositadamente, para que um contacto nunca seja atribuído ao anúncio errado.

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

Quando um contacto que já tem uma correspondência regressa através de outro anúncio e envia uma mensagem com um número de consulta mais recente, esse clique é guardado como o clique mais recente do contacto. A primeira correspondência permanece inalterada.

• Primeiro clique, para os seus relatórios: o contacto continua a mostrar de onde veio o lead inicialmente. Isso nunca muda.
• Clique mais recente, para a Meta: os eventos enviados para a Meta utilizam o clique mais recente, porque a Meta atribui o crédito ao anúncio que trouxe a pessoa de volta e apenas dentro da sua janela de atribuição. Reportar um clique antigo atribuiria o crédito ao anúncio errado, ou a nenhum.
• O clique mais recente é obtido apenas a partir de um número de consulta, nunca apenas a partir de texto correspondente, e uma visita mais antiga nunca substitui uma mais recente.

Limites:

• A primeira correspondência nunca é substituída. Os 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 mais tarde, não é correspondido.
• Apenas para o futuro: os contactos anteriores à instalação do script não têm correspondência.

Onde pode ver isto #

• Painel de contacto: Veio de um clique num anúncio com a campanha ou origem e a data do primeiro clique. Passe o rato 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 existe. As etiquetas de campanha que nunca foram preenchidas (um toque na pré-visualização de um anúncio envia o modelo da etiqueta em vez dos nomes) são omitidas. Uma visita só conta como um clique num anúncio quando a página foi aberta a partir de uma ligação de anúncio (um ID de clique da Meta ou do Google, ou etiquetas de campanha). Qualquer pessoa que tenha chegado à página de outra forma, por exemplo, a partir da pesquisa do Google, escrevendo o seu endereço ou clicando através do seu site, mostra Veio do seu site com a indicação de onde veio, como Pesquisa Google, ou Visita ao site, sem referência registada quando o navegador não indicou.
• Página de contacto: a mesma linha encontra-se abaixo do nome do contacto em Contactos, para que a veja imediatamente, também no seu telemóvel. Passe o rato ou toque para ver os detalhes.
• Atividade: a cronologia do contacto começa com Tocou no seu botão de WhatsApp após um anúncio (ou no seu site) no momento do clique, antes da sua primeira mensagem. O painel de contacto da conversa mostra a mesma linha em Atividade.
• Webhooks: contact.ad_attribution em webhooks de etiquetas de agente e em cada evento de subscrição de webhook que transporte um contacto.
• API: ad_attribution na lista de contactos e adAttribution num contacto individual, na secção Contactos da referência da API.
• Ferramentas MCP: o mesmo objeto em cada contacto que devolvem.

O valor é null quando o contacto não tem correspondência. Os campos abaixo descrevem o primeiro clique. Quando um clique posterior é correspondido, latest guarda-o com os mesmos campos; este campo está ausente até lá.

Enviar resultados para a Meta (opcional) #

Pode permitir que o Your AI Connector comunique os resultados à sua conta de anúncios Meta, para que a Meta aprenda quais os anúncios que trazem leads e vendas reais e os otimize. Isto utiliza os seus próprios detalhes da API de Conversões da Meta.

1. No Meta Events Manager, encontre o ID do seu pixel (também chamado de conjunto de dados) em Fontes de dados e crie um token de acesso em Definições, Conversions API, Gerar token de acesso.
2. Em Definições → Acompanhamento de cliques em anúncios, em Enviar resultados para a Meta (opcional), introduza o ID do pixel / conjunto de dados e o Token de acesso. Clique em Guardar detalhes da Meta.
3. Opcional: verifique a ligação. No Meta Events Manager, abra o seu pixel e vá ao separador Testar eventos, copie o código de teste aí apresentado, cole-o em Enviar um evento de teste e clique em Enviar evento de teste. A linha abaixo do botão indica “A Meta recebeu 1 evento de teste” (procure por isto em Testar eventos na Meta), ou mostra o motivo da Meta caso tenha sido recusado, por exemplo, um token incorreto. O código é utilizado apenas para esse teste e nunca é guardado.
4. Abra o editor de agentes, vá ao separador Etiquetas e abra uma etiqueta. Em Enviar para a Meta, escolha o evento: Lead, Contacto, Agendamento, Compra ou um nome personalizado. Opcionalmente, adicione um valor e uma moeda.

A partir desse momento, sempre que essa etiqueta for aplicada a um contacto (pela IA, manualmente, através da API ou por uma automatização), o Your AI Connector envia o evento para a Meta com os dados do clique mais recente do contacto (fbc, fbp, endereço IP, navegador, página de destino, a partir do clique mais recente quando existe, caso contrário, o primeiro), além do seu número de telefone, e-mail e nome, com hash, para que a Meta possa associá-lo ao anúncio. Um contacto sem correspondência continua a enviar o evento, apenas com o número de telefone, e-mail e nome com hash.

• Os eventos em direto contam sempre: um código de evento de teste nunca é armazenado com os seus detalhes da Meta, pelo que os eventos que as suas etiquetas e automatizações enviam vão sempre para os seus dados reais na Meta, nunca para o separador Testar eventos.
• Sem contagem dupla: cada evento tem um ID fixo composto pelo ID do contacto e pelo nome da etiqueta. Se o seu CRM enviar o mesmo evento para a Meta com o mesmo ID, a Meta mantém apenas um.
• Janela de atribuição da Meta: a Meta apenas atribui um evento a um anúncio dentro da sua janela de atribuição, que é, por predefinição, de 7 dias após o clique. Um negócio que se concretize semanas mais tarde não contará por si só, por isso envie também um evento anterior, por exemplo, uma etiqueta para a consulta marcada ou paga.

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

Uma etiqueta envia o seu evento quando é aplicada. Quando o resultado ocorre noutro local, como o fecho de um negócio no seu CRM ou a marcação de uma consulta, utilize a ação Enviar conversão para a Meta numa automatização. Esta ação comunica um evento ao seu conjunto de dados da Meta através da Conversions API, para que a Meta otimize os seus anúncios com base em resultados reais e não apenas em mensagens.

Utiliza os mesmos detalhes da Meta que as etiquetas: o ID do Pixel / conjunto de dados e o Token de acesso em Definições → Acompanhamento de cliques em anúncios. Sem estes, o passo falha com a mensagem “A Meta não está ligada”.

Os campos

Preencha pelo menos um dos campos: Contacto, E-mail ou Telefone. A pessoa não tem de ser um contacto: um negócio no HubSpot que atinja o estado “Closed Won” (Fechado Ganho) pode enviar uma “Purchase” (Compra) com o valor do negócio e o e-mail do comprador.

Quando seleciona um Contacto, o seu telefone, e-mail e nome são utilizados. Se a pessoa provier de um clique num anúncio que o script tenha correspondido, os detalhes do clique também são enviados, o que ajuda a Meta a associar o evento ao anúncio. O e-mail, o telefone e os nomes são encriptados antes de serem enviados. O ID do clique, o endereço IP e o browser são enviados conforme exigido pela Meta.

ID do evento e contagem dupla

A Meta conta os eventos com o mesmo nome de evento e o mesmo ID de evento apenas uma vez. Utilize um ID fixo, como o ID do negócio, quando outra ferramenta também comunica a mesma conversão, ou quando a automatização pode ser executada duas vezes para o mesmo. Deixe vazio para que seja criado um novo ID em cada execução, fazendo com que cada execução conte.

Como difere dos eventos de etiqueta

O evento Enviar para a Meta de uma etiqueta é enviado uma vez por contacto para essa etiqueta (no máximo uma vez em 30 dias). Esta ação envia sempre que é executada. O ID do evento é o que impede que uma conversão seja contada duas vezes.

Exemplo: um negócio fechado e uma consulta marcada

1. Inicie uma automatização que é executada quando um negócio é ganho: um acionador de Evento de aplicação no evento de negócio do seu CRM, com uma Condição para que apenas os negócios ganhos avancem. O HubSpot apenas envia eventos de fase de negócio para aplicações de programador, por isso, para o HubSpot, utilize um acionador de Agendamento com uma pesquisa do HubSpot para negócios que atingiram o estado “Fechado e Ganho” desde a última execução, e um Ciclo sobre os mesmos.
2. Adicione Enviar conversão para a Meta. Defina o Nome do evento como Compra, o Valor como o montante 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 marcada, inicie uma segunda automatização com o acionador Consulta marcada e adicione Enviar conversão para a Meta com o Nome do evento definido como Agendamento e o contacto do acionador em Contacto. Se desejar, adicione um segundo passo Enviar conversão para a Meta que envia uma Compra com um valor fixo, tal como o preço da consulta.

Também pode enviar uma conversão através da API com POST https://api.youraiconnector.com/v1/ad-attribution/meta-event. 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.

FAQ #

Isto funciona se o meu anúncio abrir o WhatsApp diretamente? Esses anúncios não passam pelo seu site, pelo que 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 torna o meu site mais lento ou define cookies? Carrega em segundo plano (async), não define cookies e não carrega mais nada. Apenas envia algo quando um visitante toca num botão do WhatsApp.

Posso rastrear anúncios Google, bem como anúncios Meta? Sim. Os IDs de clique do Google (gclid, gbraid, wbraid) e quaisquer etiquetas de campanha são registados e apresentados no contacto. O envio de resultados está disponível apenas para a Meta.

Porque é que um contacto não obteve uma correspondência? Os motivos mais comuns: a mensagem chegou mais de 15 minutos após o toque, o número do pedido foi removido da mensagem, o número do pedido está desligado e outro visitante enviou o mesmo texto, ou a página não tem o script.

O meu site tem ligações para dois números de WhatsApp. Posso rastrear apenas um? Sim. Escreva esse número em Número de WhatsApp nas definições. Deixe em branco para rastrear todas as ligações do WhatsApp.

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