# Understanding MatchAgents

## What is a MatchAgent?

A **MatchAgent** is the script and container that powers campaign-specific personalization on your site. It maps the page elements you want to update, applies your UTM rules, optionally uses Custom User Prompts to guide AI copy generation, and runs Rematches (split tests) if enabled. Personalization is triggered using first-party URL data only — no cookies or third-party data are used.

### Inside a MatchAgent

**1) Target Elements**

* Map H1, subhead, CTA, badges, and sections (extension recommended; CSS/data-selectors as fallback).
* If an element isn’t found at render, the visit won’t qualify the MatchAgent script to run.

**2) Targeting Rules**

* **UTM rules (required):** equals/contains on keys like `utm_source`, `utm_campaign`, `utm_term`.
  * Example: Messagematch.com/?campaign=education
* **Disqualifiers:** missing/mismatched UTMs; referrer without UTM match; exclusions; target not found.

**3) Variants & Content**

* **Baseline:** what normal traffic sees.
* **Campaign copy:** the content shown when UTM rules match.
* **Custom User Prompts:** Instructions you provide to guide how AI generates campaign copy — for example, specifying brand tone, audience, or messaging constraints (e.g., *"Write in a confident, direct tone for a B2B SaaS audience. Emphasize ROI and speed."*). Prompts are set per MatchAgent and applied at generation time. Always review and edit AI-generated copy before deploying.

**4) Rematches (optional)**

* Toggle **ON** to test up to **5** variants (even traffic split). Reported by variant in the CampaignMatch tab in the dashboard.

**5) Preview & QA**

* Test with URL params (e.g., `?utm_source=google&…`).
* Variant switching for QA available in the dashboard.

### Best practices

* Standardize UTM naming conventions before creating MatchAgents — inconsistent UTM casing or spelling will cause rules to miss.
* Start by mapping only your H1 and primary CTA. Prove the CampaignMatch works and measure lift before mapping additional elements.
* Use Custom User Prompts to lock in brand tone from the start — it's easier than editing AI-generated copy after the fact.
* Establish a stable CampaignMatch with measurable traffic before enabling Rematches. Split testing needs a baseline to be meaningful.
* Use `equals` matching for UTM rules when possible. `contains` is more flexible but increases the risk of unintended matches.

### Troubleshooting (quick)

* **No change:** verify UTMs, element mapping, Deploy status.
* **“Matches” in preview but not live:** caching—purge and retest.
* **Uneven variants:** ensure all variants are active and traffic volume is sufficient.


---

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

```
GET https://messagematch.gitbook.io/messagematch-docs/readme/key-terms/understanding-matchagents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.