> For the complete documentation index, see [llms.txt](https://docs.patagon.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.patagon.ai/marketing-e-atribuicao/capturing-attribution-data.md).

# Como capturar dados de atribuição

Antes de poder analisar qualquer coisa, a Patagon AI precisa capturar de onde vem cada conversa do WhatsApp. Existem três métodos de captura: configure os que se aplicam ao seu caso. Muitas equipes usam os três.

O script de rastreamento e o link do seu agente ficam em **Agente → Capacidades → Atribuição**.

![Agente → Capacidades → Atribuição](/files/dnjUTrDimLLg8O870cUP)

## Método 1: Botão de WhatsApp em um site ou landing page

Use este método quando os visitantes chegam ao WhatsApp clicando em um botão do seu site ou landing page. Ele captura os UTMs, os click IDs (`fbclid`, `gclid`, etc.) e a URL da página de cada visitante. Estes são os dados que o Patagon usa depois para enviar conversões de volta às suas plataformas de anúncios.

### Visão geral do fluxo

O fluxo completo tem três etapas:

1. O visitante chega à landing page com parâmetros UTM e/ou click IDs (`gclid`, `fbclid`) na URL
2. O script de rastreamento da Patagon AI lê esses parâmetros e os incorpora ao link do botão
3. Quando o visitante abre o WhatsApp, a Patagon AI usa o código de referência para associar aquela conversa à campanha correta

### Passo 1: Instalar o script de rastreamento na landing page

Vá em **Agente → Capacidades → Atribuição**, copie o script de rastreamento de uma linha e cole antes do fechamento da tag `</head>` em todas as páginas que têm (ou terão) um botão de WhatsApp ligado ao seu agente Patagon AI. É o **mesmo script para todas as páginas**:

```html
<script src="https://api.patagon.ai/api/v1/tracking.js"></script>
```

O script captura automaticamente todos os dados de campanha presentes na URL da página: parâmetros UTM (`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`), o click ID do Google (`gclid`) e o click ID da Meta (`fbclid`).

{% hint style="info" %}
Se você usa um construtor de landing pages (Elementor, Webflow, RD Station Landing Pages, Unbounce etc.), cole o script na seção de código customizado do cabeçalho da página. Se a plataforma não permitir scripts customizados, publique a landing page em um domínio próprio onde você tenha controle do HTML.
{% endhint %}

### Passo 2: Configurar o botão de WhatsApp com o link de rastreamento

Após instalar o script, **substitua o link do seu botão de WhatsApp** pelo link de rastreamento gerado pela Patagon AI. Esse link é único para cada agente e tem este formato:

```
https://patg.ai/api/v1/r/agt_01HZ0R7NA78WSNXNN9VXYZABCD?text=Olá!%20Gostaria%20de%20mais%20informações.
```

Você encontra seu link completo e personalizado em **Agente → Capacidades → Atribuição → Use este link de rastreamento no seu botão do WhatsApp**.

#### Por que não usar um link wa.me direto?

Um link `wa.me` comum não tem rastreamento. Quando o visitante clica nele, o WhatsApp abre, a conversa começa, mas a Patagon AI não sabe de onde veio esse lead. O link de rastreamento é o que permite associar a conversa à campanha, ao anúncio e à palavra-chave corretos.

#### Como personalizar a mensagem de abertura

O parâmetro `text` define a mensagem que aparece pré-preenchida quando o visitante abre o WhatsApp. Você pode personalizar por campanha adicionando o parâmetro diretamente na URL:

```
https://patg.ai/api/v1/r/agt_01HZ0R7NA78WSNXNN9VXYZABCD?text=Quero%20saber%20mais%20sobre%20o%20plano%20empresarial
```

Use textos diferentes por campanha para que seu agente identifique o contexto desde a primeira mensagem. Lembre de codificar os espaços como `%20` e caracteres especiais conforme o padrão URL encoding.

### Passo 3: Adicionar parâmetros UTM ao link do anúncio

O script só consegue capturar o que chega na URL da landing page. Por isso, seus anúncios precisam passar os UTMs corretamente.

A Patagon AI organiza a atribuição seguindo esta hierarquia fixa:

```
utm_source → utm_medium → utm_campaign → utm_content → utm_term
```

Essa hierarquia determina como as conversas são agrupadas em **Leads → Atribuição**, então mantenha a nomenclatura consistente em toda a equipe. Uma convenção recomendada:

| Parâmetro      | O que identifica                            | Exemplo                             |
| -------------- | ------------------------------------------- | ----------------------------------- |
| `utm_source`   | O canal de origem                           | `meta`, `google`, `instagram`       |
| `utm_medium`   | O tipo de tráfego                           | `cpc`, `email`, `social`, `organic` |
| `utm_campaign` | A campanha específica                       | `lancamento-produto-q2`             |
| `utm_content`  | O conjunto de anúncios ou variação          | `video-v1`, `headline-b`            |
| `utm_term`     | A palavra-chave (Search) ou nome do anúncio | `crm-para-vendas`                   |

{% hint style="warning" %}
UTMs diferenciam maiúsculas de minúsculas. `Facebook` e `facebook` aparecem como duas fontes diferentes no relatório. Defina a convenção antes de lançar e use-a em toda a equipe.
{% endhint %}

### Como o rastreamento funciona por dentro

Quando um visitante chega à landing page com UTMs na URL, o script da Patagon AI lê todos esses parâmetros e os incorpora ao shortlink de rastreamento. Quando o visitante clica no botão do WhatsApp, um pequeno código de referência é incluído na mensagem que ele envia. No momento em que essa mensagem chega ao seu agente, a Patagon AI usa esse código para atribuir automaticamente aquela conversa à campanha, ao conjunto de anúncios e ao anúncio corretos, sem nenhuma ação adicional do seu lado.

Isso significa que a janela de captura é o tempo que o visitante passa na landing page. Se ele chegar pela landing page com UTMs, fechar e voltar depois via link direto sem UTMs, a atribuição pode não ser capturada. Para mitigar isso, mantenha a janela de sessão da landing page ativa enquanto o visitante estiver na página.

### Testar o rastreamento antes de lançar a campanha

Testar antes de lançar é o que garante que você não vai perder dados de atribuição de uma campanha inteira. Siga estes passos:

#### 1. Monte uma URL de teste com UTMs

Abra a URL da sua landing page no navegador e adicione os parâmetros UTM manualmente, simulando como a URL chegaria de um anúncio:

```
https://sualandingpage.com.br/pagina?utm_source=meta&utm_medium=cpc&utm_campaign=teste-rastreamento&utm_content=video-v1&utm_term=palavra-chave
```

#### 2. Verifique se o script carregou

Abra as ferramentas do desenvolvedor do navegador (F12 → aba Network) e procure por uma requisição para `api.patagon.ai/api/v1/tracking.js`. Se ela aparecer com status 200, o script carregou corretamente.

#### 3. Clique no botão e abra o WhatsApp

Clique no botão de WhatsApp da landing page. O WhatsApp (web ou app) deve abrir com a mensagem pré-preenchida. Observe que a mensagem pode conter um código de referência invisível ao final. Isso é esperado e é o que a Patagon usa para atribuição.

#### 4. Envie a mensagem e verifique em Leads → Atribuição

Envie a mensagem pelo WhatsApp e aguarde alguns minutos. Em **Leads → Atribuição**, a conversa deve aparecer sob a fonte `meta → cpc → teste-rastreamento`. Se aparecer como **não rastreado**, verifique:

* Se o script está no `<head>` da página (não apenas no `<body>`)
* Se o link do botão é o link de rastreamento da Patagon, não um `wa.me` direto
* Se os UTMs estão na URL quando você acessa a página (alguns construtores de landing page removem parâmetros por padrão, verifique as configurações)

#### 5. Teste com o link limpo também

Acesse a landing page sem nenhum UTM e clique no botão. Essa conversa deve aparecer como **não rastreado**. Se aparecer com alguma fonte, pode haver UTMs sendo herdados de outra sessão.

### Diferenças entre link wa.me e link de rastreamento da Patagon

|                                       | Link direto `wa.me`                    | Link de rastreamento Patagon                        |
| ------------------------------------- | -------------------------------------- | --------------------------------------------------- |
| **Formato**                           | `https://wa.me/5511999999999?text=Olá` | `https://patg.ai/api/v1/r/ID_DO_AGENTE?text=Olá`    |
| **Destino**                           | Número de WhatsApp fixo                | O agente Patagon AI vinculado ao número             |
| **Captura UTMs**                      | Não                                    | Sim                                                 |
| **Captura gclid / fbclid**            | Não                                    | Sim                                                 |
| **Captura URL da página de origem**   | Não                                    | Sim                                                 |
| **Aparece em Leads → Atribuição**     | Como "não rastreado"                   | Com fonte, campanha e anúncio                       |
| **Permite roteamento por campanha**   | Não                                    | Sim (via parâmetros)                                |
| **Mensagem pré-preenchida**           | Sim (parâmetro `text`)                 | Sim (parâmetro `text`, personalizável por campanha) |
| **Envia conversões para Meta/Google** | Não                                    | Sim (quando conversões offline configuradas)        |

O link `wa.me` abre uma conversa no WhatsApp, mas a Patagon AI não consegue rastrear de onde o lead veio nem enviar conversões de leads qualificados de volta para suas plataformas de anúncios. O link de rastreamento é o que fecha esse ciclo.

### Exemplo de configuração completa

Abaixo um exemplo de como fica o botão de WhatsApp em uma landing page devidamente configurada:

```html
<!DOCTYPE html>
<html>
<head>
  <!-- Script de rastreamento Patagon AI: instale UMA VEZ no cabeçalho -->
  <script src="https://api.patagon.ai/api/v1/tracking.js"></script>
</head>
<body>

  <!-- Botão de WhatsApp usando o link de rastreamento da Patagon AI -->
  <a href="https://patg.ai/api/v1/r/SEU_ID_DE_AGENTE?text=Olá!%20Gostaria%20de%20mais%20informações.">
    Falar com especialista no WhatsApp
  </a>

</body>
</html>
```

Quando um usuário chega nessa página vindo de um anúncio com UTMs na URL, o script captura tudo automaticamente. O botão não precisa de nenhuma lógica adicional.

## Método 2: Campanhas Click-to-WhatsApp (apenas Meta)

Para os anúncios Click-to-WhatsApp (CTWA) você não marca nada manualmente. Basta **conectar sua conta da Meta** em **Leads → Atribuição → Configurações → Conectar Plataformas** (veja [Como conectar a Meta e mapear conversões](/marketing-e-atribuicao/meta-ads/meta-conversions-api.md)).

Depois que a Meta estiver conectada, cada conversa vinda de um anúncio CTWA é preenchida automaticamente:

| Parâmetro      | Valor                               |
| -------------- | ----------------------------------- |
| `utm_source`   | `meta`                              |
| `utm_medium`   | `cpc`                               |
| `utm_campaign` | o nome da campanha CTWA             |
| `utm_content`  | o nome do conjunto de anúncios CTWA |
| `utm_term`     | o nome do anúncio CTWA              |

## Método 3: Link da Patagon AI com parâmetros UTM

Use este método onde não há site nem anúncio CTWA (QR codes, botões em newsletters, materiais impressos, etc.). Pegue o link de rastreamento do seu agente (**Agente → Capacidades → Atribuição**) e adicione seus próprios parâmetros UTM:

```
https://patg.ai/api/v1/r/agt_01HZ0R7NA78WSNXNN9VXYZABCD?text=Olá!%20Gostaria%20de%20mais%20informações&utm_source={{source}}&utm_medium={{medium}}&utm_campaign={{campaign}}&utm_content={{content}}&utm_term={{term}}
```

| Parâmetro      | O que rastreia                | Exemplo                     |
| -------------- | ----------------------------- | --------------------------- |
| `utm_source`   | O canal                       | google, facebook, instagram |
| `utm_medium`   | O tipo de tráfego             | cpc, social, email, organic |
| `utm_campaign` | A campanha específica         | lancamento-produto-q2       |
| `utm_content`  | A variação criativa           | video-v1, headline-b        |
| `utm_term`     | A palavra-chave do Google Ads | crm para equipes de vendas  |

{% hint style="warning" %}
Os parâmetros UTM diferenciam maiúsculas de minúsculas. `Facebook` e `facebook` aparecem como duas fontes diferentes. Defina uma convenção de nomenclatura e use-a de forma consistente em toda a sua equipe.
{% endhint %}

## Próximos passos

* Veja seus dados capturados em [Como ler suas métricas de atribuição](/marketing-e-atribuicao/attribution-metrics.md).
* Envie conversões de leads qualificados de volta para sua plataforma de anúncios em [Como conectar a Meta e mapear conversões](/marketing-e-atribuicao/meta-ads/meta-conversions-api.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.patagon.ai/marketing-e-atribuicao/capturing-attribution-data.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.