# 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 <span data-t="appName">Your AI Connector</span> 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](click-to-whatsapp-attribution.md).

---

## 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:

{% code overflow="wrap" %}
```html
<script src="https://api.youraiconnector.com/v1/ad-visit/YOUR_SITE_KEY.js" async></script>
```
{% endcode %}

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 <span data-t="appName">Your AI Connector</span> 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 <span data-t="appName">Your AI Connector</span> 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:

{% code overflow="wrap" %}
```html
<script src="https://api.youraiconnector.com/v1/ad-visit/YOUR_SITE_KEY.js" data-manual async></script>
```
{% endcode %}

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.

{% code overflow="wrap" %}
```html
<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>
```
{% endcode %}

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 <span data-t="appName">Your AI Connector</span> quando a visita chega

Quando uma visita é correspondida, o <span data-t="appName">Your AI Connector</span> 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 <span data-t="appName">Your AI Connector</span> 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](webhooks.md#contact-tags-updated-webhook) 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.

| Campo | O que é |
|---|---|
| `visit_at` | Quando o visitante tocou no botão do WhatsApp. |
| `matched_at` | Quando a visita foi correspondida ao contato. |
| `match_method` | `reference` (correspondido pelo número da consulta) ou `text` (correspondido pelo texto idêntico da mensagem). |
| `reference` | O número da consulta, ou `null` quando estava desativado. |
| `fbc` / `fbp` | O clique da Meta e os cookies do navegador do seu próprio pixel da Meta, se presentes. |
| `fbclid` | O ID de clique de anúncio da Meta do endereço da página. |
| `gclid` / `gbraid` / `wbraid` | Os IDs de clique de anúncio do Google do endereço da página. |
| `utm_source` / `utm_medium` / `utm_campaign` / `utm_content` / `utm_term` | As tags de campanha do endereço da página. |
| `landing_url` | A página em que o visitante aterrissou. |
| `referrer` | A página de onde o visitante veio. |
| `client_ip` | O endereço IP do visitante. |
| `user_agent` | O navegador do visitante. |
| `geo_country` / `geo_region` / `geo_city` / `geo_timezone` | Localização aproximada a partir do endereço IP: código do país com duas letras, código da região, cidade e fuso horário. Ausente quando desconhecido. |
| `device_type` / `device_os` / `device_browser` | O dispositivo a partir do navegador: `mobile`, `tablet` ou `desktop`, o sistema operacional com sua versão (como `iOS 18.3`) e o navegador (como `Safari` ou `Instagram in-app`). Ausente quando desconhecido. |
| `site_key` | A chave do site do script que registrou a visita. |
| `visit_id` | O ID do registro da visita. |
| `latest` | O clique mais recente correspondido após o primeiro, com os mesmos campos. Usado para eventos enviados à Meta. Ausente quando não houver. |

---

## Enviar resultados para a Meta (opcional)

Você pode permitir que o <span data-t="appName">Your AI Connector</span> 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 <span data-t="appName">Your AI Connector</span> 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**

| Campo | O que faz |
|---|---|
| **Nome do evento** | Obrigatório. **Compra**, **Agendamento**, **Lead** ou seu próprio nome. Seu próprio nome usa letras, dígitos, espaços e sublinhados, começa com uma letra e tem no máximo 40 caracteres. |
| **Valor** e **Moeda** | O valor da conversão, como o valor do negócio. A moeda é um código de 3 letras e o padrão é EUR. O valor só é enviado quando você o preenche. |
| **Contato** | Opcional. O contato ao qual a conversão pertence. |
| **E-mail**, **Telefone**, **Nome**, **Sobrenome** | Detalhes da pessoa. Preencha-os quando a pessoa não for um contato ou para adicionar ao que o contato já possui. |
| **Seu próprio ID para a pessoa** | Um ID para a pessoa do seu próprio sistema, como um ID de CRM. |
| **ID do evento** | O ID que a Meta usa para contar o evento uma única vez. Veja abaixo. |
| **Hora do evento** | Quando a conversão aconteceu, como segundos Unix ou uma data. No máximo 7 dias atrás. Deixe vazio para usar o momento em que a etapa é executada. |
| **URL da página** | A página à qual a conversão está vinculada, se houver. |
| **Código de evento de teste** | Apenas para uma execução de teste: o código da aba Testar eventos da Meta. Um evento enviado com ele aparece em Testar eventos e não conta para seus anúncios. Deixe vazio para eventos ao vivo. |

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](click-to-whatsapp-attribution.md).

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