UTM Tracking

Make every link your AI Agent shares carry the visitor’s UTM parameters, so your analytics still knows which campaign brought them in.

Why you need this

Visitors from ads and email campaigns arrive with UTM parameters in the address, like utm_source=google. Your analytics reads them to credit the right campaign. Links your AI Agent shares in the chat don’t have them. A visitor who clicks one and signs up may not be credited to the ad that brought them in.

	Visitor lands on	AI Agent shares
Without this guide	`example.com/?utm_source=google`	`example.com/pricing`
With this guide	`example.com/?utm_source=google`	`example.com/pricing?utm_source=google`

How it works

Step	What you do	Who	Where
1. Save the UTMs	Save the UTM parameters when a visitor arrives	Developer	Your website
2. Pass them to your AI Agent	Send them to your AI Agent as user attributes	Developer	Your website
3. Update your instructions	Tell your AI Agent to add them to links	Anyone	Chatbase dashboard

Before you start

You need a website with the Chatbase embed script already installed and working. New to Chatbase? Check out Your First AI Agent to get started with the embed script first.

Step 1: Save the UTMs

UTM parameters are only in the address of the first page a visitor lands on. They’re gone once the visitor moves to another page. Your AI Agent also forgets its user attributes on every page load, so you need to send them again on each page. The fix is to save the parameters in the browser on the first visit and read them back on every page.

Add the code

Add this to your site so it runs on every page, before you call the Chatbase identify method:

function getUtmParams() {
  const keys = ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
  const url = new URLSearchParams(window.location.search);
  const saved = JSON.parse(sessionStorage.getItem("chatbase_utm") || "{}");

  // Only save UTMs if none were saved earlier this visit
  if (Object.keys(saved).length === 0) {
    for (const key of keys) {
      if (url.get(key)) saved[key] = url.get(key);
    }
    sessionStorage.setItem("chatbase_utm", JSON.stringify(saved));
  }

  return saved;
}

How the code behaves

It only keeps the five standard UTM keys. Anything else in the address is ignored. This keeps random query parameters away from your AI Agent and keeps the attributes short.
It keeps the first UTMs it sees. If the visitor later clicks through from a different campaign in the same session, the original source is kept. To credit the most recent campaign instead, remove the if check so new UTMs replace the saved ones.
It uses sessionStorage. The parameters are cleared when the visitor closes the tab. Use localStorage instead if you want them to last across visits.

Step 2: Pass them to your AI Agent

Send the saved parameters to your AI Agent as user attributes. Your AI Agent reads user attributes while it replies, so it will know which campaign the visitor came from. Pick the tab that matches your visitors. If your website has both logged-in and logged-out visitors, you need both.

Anonymous visitors
Logged-in visitors

For visitors who aren’t logged in, pass the parameters inside user_metadata. You don’t need a token or a user ID.

window.chatbase("identify", {
  user_metadata: getUtmParams()
});

To set this up before the Chatbase script loads, use window.chatbaseUserConfig instead:

<script>
  window.chatbaseUserConfig = {
    user_metadata: getUtmParams()
  };
</script>

<!-- Your normal Chatbase embed script -->

If you already identify logged-in users with a JWT, add the UTM parameters to the identify call you already have. Put them next to the token, the same way you pass other public attributes:

const token = await getJWTFromBackend();

window.chatbase("identify", {
  token: token,
  name: user.firstName,
  ...getUtmParams()
});

Don’t add a second identify call just for the UTM parameters. Each identify call replaces the attributes from the last one. A separate call would erase the name, token, or anything else you passed before.

Still using the older user hash method? Add the UTM parameters to the user_metadata object you already send.

User attributes are visible to your AI Agent. UTM parameters aren’t sensitive, so this is fine. Still, never put private information in these attributes. That belongs inside the signed token.

Step 3: Update your instructions

Your AI Agent now knows where the visitor came from, but it won’t do anything with that on its own. You need to tell it what to do in its instructions.

What your AI Agent sees

Each attribute appears as a line of text at the start of the conversation, like this:

user utm_source: google
user utm_medium: cpc
user utm_campaign: spring_sale

Add the instructions

Open your instructions

In your Chatbase Dashboard, open your AI Agent and go to Build > Instructions.

Paste the text below

Add it to the end of your instructions, and replace example.com with your own domain.

Save

Click Save changes.

### Links and UTM parameters
At the start of the conversation you may see lines such as "user utm_source: google" or "user utm_campaign: spring_sale". These are the visitor's UTM parameters.

Whenever you share a link to example.com, add every UTM parameter you were given to the end of the link.
- If the link has no "?" yet, start with "?", for example: https://example.com/pricing?utm_source=google&utm_campaign=spring_sale
- If the link already has a "?", add them with "&" instead.
- Use the parameter names and values exactly as given. Don't change, translate, or invent them.
- Only do this for links to example.com. Leave links to other websites unchanged.
- If you weren't given any UTM parameters, share links unchanged. Never make up UTM values.
- Don't mention UTM parameters or tracking to the visitor. Just share the link.

For more on writing instructions, see Build.

AI models usually follow clear instructions like these, but not every time, so your AI Agent may now and then share a link without the parameters. Test it on your own site before you depend on it.

Test it

Visit your site with test UTMs

Open your website with test parameters in the address, for example https://example.com/?utm_source=test&utm_campaign=chatbase_check.

Ask for a link

Open the chat and ask something that should get a link back, like “Where can I see your pricing?”

Check the link

The link in the reply should end with utm_source=test&utm_campaign=chatbase_check.

Try another page

Go to another page on your site and ask for another link. The same UTM parameters should still be there.

Test in the widget on your own website, not in the Playground. The Playground doesn’t run your site’s code, so it never receives the UTM parameters.

Troubleshooting

The link comes back without UTM parameters

Open your browser’s developer console and run sessionStorage.getItem("chatbase_utm"). If it shows null or "{}", the parameters weren’t saved. Make sure the code from Step 1 runs on the page you landed on.
Check that identify runs on every page, not just the first one.
Look for a second identify call elsewhere on your site. It would replace the UTM attributes.
Make sure you saved the updated instructions, and that the domain in them matches your site.

Good to know

Source cards don't get UTM parameters

The source cards shown under a reply link to your data sources as they are. Only links your AI Agent writes in the reply itself get the UTM parameters.

Keep user attributes short

All user attributes together are cut off at 1,000 characters. The five UTM parameters are well under that. If you also pass many other attributes, the last ones may not reach your AI Agent.

Instructions can't use placeholders

There’s no {{utm_source}} placeholder syntax in instructions. Your AI Agent reads the attribute lines and adds the values itself, which is why the instructions above describe what the lines look like.

Using a fixed tag instead

To tag every link as coming from the chat, like utm_source=chatbase, you don’t need Steps 1 and 2. Tell your AI Agent in its instructions to add those exact parameters to every link to your domain.

Next steps

Identity Verification

Identify logged-in users and pass more attributes to your AI Agent

Event Listeners

Learn to listen for and respond to chat events in real-time

Custom Initial Messages

Create dynamic, personalized initial messages for users

Getting Started

JavaScript Embed Features

Advanced Integration

Widgets

API v1 Reference

Why you need this

How it works

Before you start

Step 1: Save the UTMs

Add the code

How the code behaves

Step 2: Pass them to your AI Agent

Step 3: Update your instructions

What your AI Agent sees

Add the instructions

Test it

Troubleshooting

Good to know

Next steps

Identity Verification

Event Listeners

Custom Initial Messages

​Why you need this

​How it works

​Before you start

​Step 1: Save the UTMs

​Add the code

​How the code behaves

​Step 2: Pass them to your AI Agent

​Step 3: Update your instructions

​What your AI Agent sees

​Add the instructions

​Test it

​Troubleshooting

​Good to know

​Next steps

Identity Verification

Event Listeners

Custom Initial Messages

Why you need this

How it works

Before you start

Step 1: Save the UTMs

Add the code

How the code behaves

Step 2: Pass them to your AI Agent

Step 3: Update your instructions

What your AI Agent sees

Add the instructions

Test it

Troubleshooting

Good to know

Next steps