> 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/en/marketing-and-attribution/capturing-attribution-data.md).

# How to capture attribution data

Before you can analyze anything, Patagon AI needs to capture where each WhatsApp conversation comes from. There are three capture methods — set up whichever apply to you. Many teams use all three.

The tracking script and your agent's link both live under **Agent → Capabilities → Attribution**.

![Agent → Capabilities → Attribution](/files/DwHKd5VTJ8Zsipp0TGbC)

## Method 1 — WhatsApp button on a website or landing page

Use this when visitors reach WhatsApp by clicking a button on your site or landing page. It captures the UTMs, click IDs (`fbclid`, `gclid`, etc.), and the page URL of each visitor — the data Patagon later uses to send conversions back to your ad platforms.

### Flow overview

The complete flow has three stages:

1. The visitor arrives at the landing page with UTM parameters and/or click IDs (`gclid`, `fbclid`) in the URL
2. The Patagon AI tracking script reads those parameters and incorporates them into the button link
3. When the visitor opens WhatsApp, Patagon AI uses the reference code to associate that conversation with the correct campaign

### Step 1: Install the tracking script on the landing page

Go to **Agent → Capabilities → Attribution**, copy the one-line tracking script and paste it before the closing `</head>` tag on all pages that have (or will have) a WhatsApp button linked to your Patagon AI agent. It's the **same script for all pages**:

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

The script automatically captures all campaign data present in the page URL: UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`), Google's click ID (`gclid`), and Meta's click ID (`fbclid`).

{% hint style="info" %}
If you use a landing page builder (Elementor, Webflow, RD Station Landing Pages, Unbounce, etc.), paste the script in the custom code section of the page header. If the platform doesn't allow custom scripts, publish the landing page on your own domain where you have HTML control.
{% endhint %}

### Step 2: Configure the WhatsApp button with the tracking link

After installing the script, **replace your WhatsApp button link** with the tracking link generated by Patagon AI. This link is unique for each agent and has this format:

```
https://patg.ai/api/v1/r/agt_01HZ0R7NA78WSNXNN9VXYZABCD?text=Hi!%20I'd%20like%20more%20information.
```

You'll find your complete and personalized link in **Agent → Capabilities → Attribution → Use this tracking link on your WhatsApp button**.

#### Why not use a direct wa.me link?

A common `wa.me` link has no tracking. When the visitor clicks it, WhatsApp opens, the conversation begins, but Patagon AI doesn't know where that lead came from. The tracking link is what allows associating the conversation with the correct campaign, ad, and keyword.

#### How to customize the opening message

The `text` parameter defines the message that appears pre-filled when the visitor opens WhatsApp. You can customize it per campaign by adding the parameter directly in the URL:

```
https://patg.ai/api/v1/r/agt_01HZ0R7NA78WSNXNN9VXYZABCD?text=I%20want%20to%20know%20more%20about%20the%20enterprise%20plan
```

Use different texts per campaign so your agent identifies the context from the first message. Remember to encode spaces as `%20` and special characters according to URL encoding standards.

### Step 3: Add UTM parameters to the ad link

The script can only capture what arrives in the landing page URL. That's why your ads need to pass the UTMs correctly.

Patagon AI organizes attribution following this fixed hierarchy:

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

This hierarchy determines how conversations are grouped in **Leads → Attribution**, so keep the naming consistent across the team. A recommended convention:

| Parameter      | What it identifies              | Example                             |
| -------------- | ------------------------------- | ----------------------------------- |
| `utm_source`   | The source channel              | `meta`, `google`, `instagram`       |
| `utm_medium`   | The traffic type                | `cpc`, `email`, `social`, `organic` |
| `utm_campaign` | The specific campaign           | `product-launch-q2`                 |
| `utm_content`  | The ad set or variation         | `video-v1`, `headline-b`            |
| `utm_term`     | The keyword (Search) or ad name | `crm-for-sales`                     |

{% hint style="warning" %}
UTMs are case-sensitive. `Facebook` and `facebook` appear as two different sources in the report. Define the convention before launching and use it across the entire team.
{% endhint %}

### How tracking works under the hood

When a visitor arrives at the landing page with UTMs in the URL, the Patagon AI script reads all those parameters and incorporates them into the tracking shortlink. When the visitor clicks the WhatsApp button, a small reference code is included in the message they send. The moment that message reaches your agent, Patagon AI uses that code to automatically attribute that conversation to the correct campaign, ad set, and ad, without any additional action on your part.

This means the capture window is the time the visitor spends on the landing page. If they arrive via the landing page with UTMs, close, and return later via a direct link without UTMs, attribution may not be captured. To mitigate this, keep the landing page session window active while the visitor is on the page.

### Test tracking before launching the campaign

Testing before launching is what ensures you won't lose attribution data from an entire campaign. Follow these steps:

#### 1. Build a test URL with UTMs

Open your landing page URL in the browser and add UTM parameters manually, simulating how the URL would arrive from an ad:

```
https://yourlandingpage.com/page?utm_source=meta&utm_medium=cpc&utm_campaign=tracking-test&utm_content=video-v1&utm_term=keyword
```

#### 2. Verify the script loaded

Open the browser's developer tools (F12 → Network tab) and look for a request to `api.patagon.ai/api/v1/tracking.js`. If it appears with status 200, the script loaded correctly.

#### 3. Click the button and open WhatsApp

Click the WhatsApp button on the landing page. WhatsApp (web or app) should open with the pre-filled message. Notice that the message may contain an invisible reference code at the end. This is expected and is what Patagon uses for attribution.

#### 4. Send the message and check in Leads → Attribution

Send the message via WhatsApp and wait a few minutes. In **Leads → Attribution**, the conversation should appear under the source `meta → cpc → tracking-test`. If it appears as **untracked**, verify:

* If the script is in the page's `<head>` (not just in `<body>`)
* If the button link is Patagon's tracking link, not a direct `wa.me`
* If the UTMs are in the URL when you access the page (some landing page builders remove parameters by default, check the settings)

#### 5. Test with the clean link too

Access the landing page without any UTM and click the button. This conversation should appear as **untracked**. If it appears with some source, there may be UTMs being inherited from another session.

### Differences between wa.me link and Patagon tracking link

|                                      | Direct `wa.me` link                      | Patagon tracking link                             |
| ------------------------------------ | ---------------------------------------- | ------------------------------------------------- |
| **Format**                           | `https://wa.me/5511999999999?text=Hello` | `https://patg.ai/api/v1/r/AGENT_ID?text=Hello`    |
| **Destination**                      | Fixed WhatsApp number                    | The Patagon AI agent linked to the number         |
| **Captures UTMs**                    | No                                       | Yes                                               |
| **Captures gclid / fbclid**          | No                                       | Yes                                               |
| **Captures origin page URL**         | No                                       | Yes                                               |
| **Appears in Leads → Attribution**   | As "untracked"                           | With source, campaign, and ad                     |
| **Allows routing by campaign**       | No                                       | Yes (via parameters)                              |
| **Pre-filled message**               | Yes (`text` parameter)                   | Yes (`text` parameter, customizable per campaign) |
| **Sends conversions to Meta/Google** | No                                       | Yes (when offline conversions configured)         |

The `wa.me` link opens a conversation in WhatsApp, but Patagon AI can't track where the lead came from nor send qualified lead conversions back to your advertising platforms. The tracking link is what closes that loop.

### Complete configuration example

Below is an example of how the WhatsApp button looks on a properly configured landing page:

```html
<!DOCTYPE html>
<html>
<head>
  <!-- Patagon AI tracking script: install ONCE in the header -->
  <script src="https://api.patagon.ai/api/v1/tracking.js"></script>
</head>
<body>

  <!-- WhatsApp button using Patagon AI tracking link -->
  <a href="https://patg.ai/api/v1/r/YOUR_AGENT_ID?text=Hi!%20I'd%20like%20more%20information.">
    Talk to a specialist on WhatsApp
  </a>

</body>
</html>
```

When a user arrives on this page from an ad with UTMs in the URL, the script captures everything automatically. The button doesn't need any additional logic.

## Method 2 — Click-to-WhatsApp campaigns (Meta only)

For Click-to-WhatsApp (CTWA) ads you don't tag anything by hand. Just **connect your Meta account** in **Leads → Attribution → Settings → Connect Platforms** (see [How to connect Meta and map conversions](/en/marketing-and-attribution/meta-ads/meta-conversions-api.md)).

Once Meta is connected, every conversation that comes from a CTWA ad is filled in automatically:

| Parameter      | Value                  |
| -------------- | ---------------------- |
| `utm_source`   | `meta`                 |
| `utm_medium`   | `cpc`                  |
| `utm_campaign` | the CTWA campaign name |
| `utm_content`  | the CTWA ad set name   |
| `utm_term`     | the CTWA ad name       |

## Method 3 — Patagon AI link with UTM parameters

Use this anywhere there's no website or CTWA ad — QR codes, newsletter buttons, printed marketing assets, and so on. Take your agent's tracking link (**Agent → Capabilities → Attribution**) and append your own UTM parameters:

```
https://patg.ai/api/v1/r/agt_01HZ0R7NA78WSNXNN9VXYZABCD?text=Hi!%20I%20would%20like%20more%20information&utm_source={{source}}&utm_medium={{medium}}&utm_campaign={{campaign}}&utm_content={{content}}&utm_term={{term}}
```

| Parameter      | What it tracks           | Example                     |
| -------------- | ------------------------ | --------------------------- |
| `utm_source`   | The channel              | google, facebook, instagram |
| `utm_medium`   | The traffic type         | cpc, social, email, organic |
| `utm_campaign` | The specific campaign    | product-launch-q2           |
| `utm_content`  | The creative variation   | video-v1, headline-b        |
| `utm_term`     | The keyword (Google Ads) | crm for sales teams         |

{% hint style="warning" %}
UTM parameters are case-sensitive. `Facebook` and `facebook` appear as two different sources. Define a naming convention and use it consistently across your team.
{% endhint %}

## Next steps

* See your captured data in [How to read your attribution metrics](/en/marketing-and-attribution/attribution-metrics.md).
* Send qualified-lead conversions back to your ad platform in [How to connect Meta and map conversions](/en/marketing-and-attribution/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/en/marketing-and-attribution/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.