> For the complete documentation index, see [llms.txt](https://messagematch.gitbook.io/messagematch-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://messagematch.gitbook.io/messagematch-docs/readme/key-terms/understanding-matchagents.md).

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