Ad click attribution for WhatsApp #

If you run Meta or Google ads to a page on your own website, and that page has a WhatsApp button, Your AI Connector can tell you which ad click each WhatsApp conversation came from. You paste one small script on your website. When a visitor taps your WhatsApp button, the click is remembered and matched to the first message they send you. The contact then shows the campaign it came from, and the click data travels with the contact into webhooks, the API and, if you want, back to Meta.

This works for any page with a WhatsApp button: a landing page, a booking page, a price page or a quiz that ends in “Send my answers on WhatsApp”.

This page is about ads that send people to your website first. If your ads open WhatsApp directly (Meta’s “Click to WhatsApp” ads), that is covered automatically, without a script, in Click-to-WhatsApp Ad Attribution.

Set it up #

1. Go to Settings → Ad click tracking (Integrations group).
2. Click Turn on and get my script. Your account gets its own site key and a one line script.
3. Copy the script and paste it just before the closing </body> tag on every page that has a WhatsApp button:

<script src="https://api.youraiconnector.com/v1/ad-visit/YOUR_SITE_KEY.js" async></script>

4. Optional: under WhatsApp number, type the number your buttons link to. Only links to that number are then tracked. Leave it empty to track every WhatsApp link on the site.
5. Choose the wording of the enquiry number (see below) and click Save. You do not need to change the script on your website after a settings change.
6. Test it: open your page from a link with a campaign tag on it, for example https://yoursite.com/?utm_source=test&utm_campaign=setup-check, tap your own WhatsApp button and send the message. Open that contact in Chats: the contact panel shows Came from an ad click with the campaign.

The site key is already inside the script. It is not a password, so it is fine on a public page.

What the script does #

• When the page loads, it keeps the ad click ids and campaign tags (the utm_ parameters) from the page address in the browser tab’s session storage, so they are still there if the visitor looks at another page first. It sets no cookie, loads nothing else and sends nothing.
• When the visitor taps a WhatsApp link (wa.me, api.whatsapp.com/send or whatsapp://send), it adds the enquiry number to the message, records the visit and lets the tap continue to WhatsApp as normal.

Nothing is sent to Your AI Connector before the tap.

The enquiry number #

A short number, like the reference a shop or clinic gives you, is added to the visitor’s WhatsApp message. It is how Your AI Connector knows exactly which ad click belongs to which conversation. A message looks like this:

Hi, I would like to know more.
Enquiry no. 4827

• Wording: “Enquiry no.” is the default. You can use any one line of text that sounds natural for your business, such as “Booking ref” or “Ref”. No digits.
• Where: On its own last line (the default) or At the end of the text. The settings page shows a live preview.
• Length: 4 digits, or 5 when your site is very busy.
• Your AI agent never sees it and never repeats it. The inbox shows the full message, number included.

You can switch the enquiry number off. Matching then only works on the text of the message, so two visitors who send exactly the same text (for example the same quiz answers) cannot be told apart, and some clicks will not be matched.

Your own quiz or button code #

If your page builds the WhatsApp message itself (a quiz that puts the answers in the text, or your own button code), add data-manual to the script tag:

<script src="https://api.youraiconnector.com/v1/ad-visit/YOUR_SITE_KEY.js" data-manual async></script>

With data-manual the script no longer changes WhatsApp links by itself. Your own code calls it right before it opens WhatsApp, so each visit is recorded once:

• window.ChatAttribution.text(finalText, number) returns your text with the enquiry number added, and records the visit. Use the returned text in your WhatsApp link.
• window.ChatAttribution.link(finalText, number) does the same and returns a ready wa.me link with that text. Leave out the number to use the one under WhatsApp number in the settings.

<script>
  function sendAnswers(answers) {
    var text = "Hi, my answers: " + answers.join(", ");
    if (window.ChatAttribution) {
      window.location.href = window.ChatAttribution.link(text, "+15551234567");
    } else {
      window.location.href = "https://wa.me/15551234567?text=" + encodeURIComponent(text);
    }
  }
</script>

The else branch keeps the button working if the script has not loaded, for example when a browser extension blocks it. A text that already carries a number the script issued is never changed a second time.

What gets recorded #

At the tap, the visit record holds:

• the ad click ids in the page address, such as fbclid (Meta) and gclid (Google)
• the _fbc and _fbp cookies, if your own Meta pixel set them on your site (the script reads them, it never sets them)
• the campaign tags (utm_source, utm_medium, utm_campaign, utm_content, utm_term)
• the landing page, the page the visitor came from, the browser, and the message text
• the IP address and the time, added by Your AI Connector when the visit arrives

When a visit is matched, Your AI Connector also works out from that data roughly where the visitor was (city and country, approximate, from the IP address) and which device they used (phone, tablet or computer, the operating system and the browser, for example the Instagram in-app browser). Location stays empty when it cannot be worked out, which is common on mobile networks.

Visit records are kept for 90 days. When a visit is matched, a copy of its click data is stored on the contact and stays with the contact until you delete it.

Your privacy notice: the script runs on your website, so your website’s privacy notice should mention it: what it records (the list above) and that it does so when a visitor taps a WhatsApp button.

How matching works #

When a contact’s first message arrives, Your AI Connector looks for a visit from the 15 minutes before it:

1. By enquiry number first. A message carrying a number the script issued is matched to that visit.
2. Otherwise by identical text. A message with exactly the same text as one visit is matched to it. When two different visitors sent the same text inside the window, neither is matched, on purpose, so a contact is never credited to the wrong ad.

A later message that carries the enquiry number is also matched, as long as the contact has no match yet.

When a contact who already has a match comes back through another ad and sends a message carrying a newer enquiry number, that click is kept as the contact’s latest click. The first match stays as it is.

• First click, for your reporting: the contact keeps showing where the lead first came from. That never changes.
• Latest click, for Meta: events sent to Meta use the newest click, because Meta credits the ad that brought the person back and only inside its attribution window. Reporting an old click would credit the wrong ad, or none at all.
• The latest click is only taken from an enquiry number, never from matching text alone, and an older visit never replaces a newer one.

Limits:

• The first match is never overwritten. Newer clicks go into the latest click.
• WhatsApp only: the WhatsApp Business API and WhatsApp Web channels.
• 15 minutes: a visitor who taps the button but sends the message much later is not matched.
• Going forward only: contacts from before you installed the script have no match.

Where you see it #

• Contact panel: Came from an ad click with the campaign or source and the date of the first click. Hover for the details: the campaign, the Ad (utm_content) and Ad set (utm_term), the approximate Location and the Device, each only when it is known, plus the same for the latest click when there is one. Campaign tags that were never filled in (an ad preview tap sends the tag template instead of the names) are left out. A visit only counts as an ad click when the page was opened from an ad link (a Meta or Google click id, or campaign tags). Anyone who reached the page another way, for example from Google search, by typing your address or by clicking through your site, shows Came from your website with where they came from, such as Google search, or Website visit, no referrer recorded when the browser did not say.
• Contact page: the same line sits under the contact’s name in Contacts, so you see it straight away, on your phone too. Hover or tap it for the details.
• Activity: the contact’s timeline starts with Tapped your WhatsApp button after an ad (or on your website) at the time of the click, before their first message. The chat’s contact panel shows the same line under Activity.
• Webhooks: contact.ad_attribution in agent tag webhooks and in every webhook subscription event that carries a contact.
• API: ad_attribution on the contact list and adAttribution on a single contact, in the Contacts section of the API reference.
• MCP tools: the same object on every contact they return.

The value is null when the contact has no match. The fields below describe the first click. When a later click was matched, latest holds it with the same fields; it is absent until then.

Send results to Meta (optional) #

You can let Your AI Connector report outcomes back to your Meta ad account, so Meta learns which ads bring real leads and sales and optimises toward them. This uses your own Meta Conversions API details.

1. In Meta Events Manager, find your pixel (also called dataset) ID under Data sources, and create an access token under Settings, Conversions API, Generate access token.
2. In Settings → Ad click tracking, under Send results to Meta (optional), enter the Pixel / dataset ID and the Access token. Click Save Meta details.
3. Optional: check the connection. In Meta Events Manager, open your pixel and go to the Test events tab, copy the test code shown there, paste it under Send a test event and click Send test event. The line below the button says “Meta received 1 test event” (look for it under Test events in Meta), or shows Meta’s reason when it was refused, for example a wrong token. The code is used for that one test only and is never saved.
4. Open the agent editor, go to the Tags tab and open a tag. Under Send to Meta, choose the event: Lead, Contact, Schedule, Purchase or a custom name. Optionally add a value and a currency.

From then on, whenever that tag is applied to a contact (by the AI, by hand, through the API or by an automation), Your AI Connector sends the event to Meta with the contact’s newest click data (fbc, fbp, IP address, browser, landing page, from the latest click when there is one, else the first) plus their phone, email and name, hashed, so Meta can link it to the ad. A contact without a match still sends the event, with only the hashed phone, email and name.

• Live events always count: a test event code is never stored with your Meta details, so the events your tags and automations send always go to your real data in Meta, never to the Test events tab.
• No double counting: each event has a fixed id made of the contact id and the tag name. If your CRM sends the same event to Meta with the same id, Meta keeps only one.
• Meta’s attribution window: Meta only credits an event to an ad inside its attribution window, which is 7 days after the click by default. A deal that closes weeks later will not count on its own, so also send an earlier event, for example a tag for the booked or paid consultation.

Send conversions from automations #

A tag sends its event when the tag is applied. When the result happens somewhere else, such as a deal closing in your CRM or a consult being booked, use the Send conversion to Meta action in an automation. It reports one event to your Meta dataset through the Conversions API, so Meta optimises your ads on real results and not only on messages.

It uses the same Meta details as the tags: the Pixel / dataset ID and Access token under Settings → Ad click tracking. Without them the step fails with “Meta is not connected”.

The fields

Fill in at least one of Contact, Email or Phone. The person does not have to be a contact: a HubSpot deal that reaches Closed Won can send a Purchase with the deal amount and the buyer’s email.

When you pick a Contact, their phone, email and name are used. If they came from an ad click that the script matched, the click details go along too, which helps Meta match the event to the ad. Email, phone and names are hashed before they leave. The click id, IP address and browser are sent as Meta requires.

Event ID and double counting

Meta counts events with the same event name and the same Event ID once. Use a fixed id, such as the deal id, when another tool also reports the same conversion, or when the automation might run twice for it. Leave it empty and a new id is made on every run, so every run counts.

How it differs from tag events

A tag’s Send to Meta event goes out once per contact for that tag (at most once in 30 days). This action sends every time it runs. The Event ID is what stops a conversion being counted twice.

Example: a closed deal and a booked consult

1. Start an automation that runs when a deal is won: an App event trigger on your CRM’s deal event, with a Condition so only won deals go on. HubSpot only sends deal-stage events to developer apps, so for HubSpot use a Schedule trigger with a HubSpot search for deals that reached Closed Won since the last run, and a Loop over them.
2. Add Send conversion to Meta. Set Event name to Purchase, Value to the deal amount (insert it with the + button) and Currency to your currency. Put the buyer’s email in Email and the deal id in Event ID, so the same deal is never counted twice.
3. For a booked consult, start a second automation with the Appointment booked trigger and add Send conversion to Meta with Event name set to Schedule and the contact from the trigger in Contact. If you want, add a second Send conversion to Meta step that sends a Purchase with a fixed value, such as the price of the consult.

You can also send a conversion over the API with POST https://api.youraiconnector.com/v1/ad-attribution/meta-event. It takes the same fields in snake case: event_name, value, currency, contact_id, email, phone, first_name, last_name, external_id, event_id, event_time, event_source_url and test_event_code.

FAQ #

Does this work if my ad opens WhatsApp directly? Those ads do not pass through your website, so the script never runs. Meta sends the ad details with the first message instead, see Click-to-WhatsApp Ad Attribution.

Does the script slow down my website or set cookies? It loads in the background (async), sets no cookie and loads nothing else. It only sends something when a visitor taps a WhatsApp button.

Can I track Google Ads as well as Meta ads? Yes. Google click ids (gclid, gbraid, wbraid) and any campaign tags are recorded and shown on the contact. Sending results back is available for Meta only.

Why did a contact not get a match? The most common reasons: the message arrived more than 15 minutes after the tap, the enquiry number was removed from the message, the enquiry number is off and another visitor sent the same text, or the page does not have the script.

My website links to two WhatsApp numbers. Can I track only one? Yes. Type that number under WhatsApp number in the settings. Leave it empty to track every WhatsApp link.

Can I change the wording later? Yes. Changes apply to your website straight away; you do not need to paste the script again.