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

---

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

{% 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 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.

::: master-only
**Agências:** cada conta de cliente tem a sua própria chave de site e script, pelo que o site de cada cliente reporta para a sua própria conta. Pode ocultar a secção para um cliente com a visibilidade de menu, tal como qualquer outra secção de definições.
:::

---

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

{% 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 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.

{% 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 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 <span data-t="appName">DM Champ</span> quando a visita chega

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 <span data-t="appName">DM Champ</span> 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 contactos:** **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, incluindo o clique mais recente, quando existir.
- **Webhooks:** `contact.ad_attribution` em [webhooks de etiquetas de agente](webhooks.md#contact-tags-updated-webhook) e em cada evento de subscrição de webhook que contenha 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á.

| Campo | O que é |
|---|---|
| `visit_at` | Quando o visitante tocou no botão do WhatsApp. |
| `matched_at` | Quando a visita foi correspondida ao contacto. |
| `match_method` | `reference` (correspondido pelo número de consulta) ou `text` (correspondido por texto de mensagem idêntico). |
| `reference` | O número de 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 do anúncio da Meta a partir do endereço da página. |
| `gclid` / `gbraid` / `wbraid` | Os IDs de clique dos anúncios do Google a partir do endereço da página. |
| `utm_source` / `utm_medium` / `utm_campaign` / `utm_content` / `utm_term` | As etiquetas de campanha a partir do endereço da página. |
| `landing_url` | A página onde o visitante aterrou. |
| `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 registou a visita. |
| `visit_id` | O ID do registo da visita. |
| `latest` | O clique mais recente correspondido após o primeiro, com os mesmos campos. Utilizado para eventos enviados para a Meta. Ausente quando não existe. |

---

## Enviar resultados para a Meta (opcional)

Pode permitir que o <span data-t="appName">DM Champ</span> 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 <span data-t="appName">DM Champ</span> 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**

| Campo | O que faz |
|---|---|
| **Nome do evento** | Obrigatório. **Compra**, **Agendamento**, **Lead** ou o seu próprio nome. O seu próprio nome utiliza letras, dígitos, espaços e sublinhados, começa com uma letra e tem no máximo 40 caracteres. |
| **Valor** e **Moeda** | O montante da conversão, como o valor do negócio. A moeda é um código de 3 letras e, por predefinição, é EUR. O valor só é enviado quando o preenche. |
| **Contacto** | Opcional. O contacto a que a conversão pertence. |
| **E-mail**, **Telefone**, **Nome próprio**, **Apelido** | Detalhes da pessoa. Preencha estes campos quando a pessoa não for um contacto, ou para adicionar ao que o contacto já possui. |
| **O 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 utiliza para contar o evento apenas uma vez. Veja abaixo. |
| **Hora do evento** | Quando a conversão ocorreu, em segundos unix ou numa data. No máximo há 7 dias. Deixe vazio para utilizar o momento em que o passo é executado. |
| **URL da página** | A página a que a conversão está ligada, se aplicável. |
| **Código de evento de teste** | Apenas para uma execução de teste: o código do separador Testar eventos da Meta. Um evento enviado com este código aparece em Testar eventos e não conta para os seus anúncios. Deixe vazio para eventos em direto. |

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 com o gatilho **Evento da aplicação**, selecione **HubSpot** e **Fase do negócio atualizada**, e adicione uma **Condição** para que apenas os negócios "Closed Won" avancem.
2. Adicione **Enviar conversão para a Meta**. Defina o **Nome do evento** como **Purchase**, 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 contado duas vezes.
3. Para uma consulta marcada, inicie uma segunda automatização com o gatilho **Consulta marcada** e adicione **Enviar conversão para a Meta** com o **Nome do evento** definido como **Schedule** e o contacto do gatilho em **Contacto**. Se desejar, adicione um segundo passo **Enviar conversão para a Meta** que envia uma **Purchase** com um valor fixo, como o preço da consulta.

Também pode enviar uma conversão através da API com `POST https://api.dmchamp.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](click-to-whatsapp-attribution.md).

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