# 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">DM Champ</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.dmchamp.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.

::: master-only
**Agências:** cada conta de cliente tem sua própria chave de site e script, para que o site de cada cliente relate para sua própria conta. Você pode ocultar a seção para um cliente com visibilidade de menu, como qualquer outra seção de configurações.
:::

---

## 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">DM Champ</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">DM Champ</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.dmchamp.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">DM Champ</span> quando a visita chega

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">DM Champ</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.

Limites:

- **A primeira correspondência vence.** Uma vez que um contato tenha uma correspondência, ela nunca é sobrescrita.
- **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. Passe o mouse para ver os detalhes.
- **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.

| 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 a partir do endereço da página. |
| `gclid` / `gbraid` / `wbraid` | Os IDs de clique de anúncio do Google a partir do endereço da página. |
| `utm_source` / `utm_medium` / `utm_campaign` / `utm_content` / `utm_term` | As tags de campanha a partir 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. |
| `site_key` | A chave do site do script que registrou a visita. |
| `visit_id` | O ID do registro da visita. |

---

## Enviar resultados para a Meta (opcional)

Você pode permitir que o <span data-t="appName">DM Champ</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**. Durante os testes, você pode adicionar o **Código de evento de teste** da aba Eventos de teste da Meta; limpe-o quando terminar. Clique em **Salvar detalhes da Meta**.
3. 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">DM Champ</span> envia o evento para a Meta com os dados de clique armazenados do contato (`fbc`, `fbp`, endereço IP, navegador, página de destino) mais seu telefone, e-mail e nome, hashados, para que a Meta possa vinculá-los ao anúncio. Um contato sem correspondência ainda envia o evento, apenas com o telefone, e-mail e nome hashados.

- **Sem contagem dupla:** cada evento possui um ID fixo composto pelo ID do contato e o nome da tag. 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 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 fecha semanas depois não contará por si só, então envie também um evento anterior, por exemplo, uma tag para a consulta agendada ou paga.

---

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