Your AI Connector Docs

Click-to-WhatsApp Ad Attribution

If you run Meta (Facebook/Instagram) “Click to WhatsApp” ads, Your AI Connector can tell you which ad each WhatsApp lead came from — and hand you the Meta click identifier you need to report real conversions back to Meta. This lets your ad campaigns optimize for actual sales and bookings, not just for “people who started a chat.”

What Gets Captured

When someone taps a Click-to-WhatsApp ad and messages your business, Meta attaches hidden referral information to that first message. Your AI Connector reads it automatically and stores it on the contact. No setup, no configuration — it just happens.

The captured information is stored on the contact as ad_referral and contains:

Field What it is
ctwa_clid The Meta click identifier. This is the value you send to Meta’s Conversions API to attribute a downstream conversion back to the exact ad click. Empty for organic post referrals (see below).
source_id The ID of the ad (or post) the person clicked.
source_type Either ad (a paid Click-to-WhatsApp ad) or post (an organic Facebook/Instagram post).
source_url The link associated with the ad content.
headline The ad’s headline text.
body The ad’s body text.
channel The channel the referral arrived on (currently always whatsapp).
captured_at When the referral was first recorded on the contact.

You can see this on a contact’s quick-view panel if you’ve configured a custom field for it, or read it directly through webhooks and the API (see below) — it isn’t broken out as its own labeled field in the Contacts table.

One thing the payload does not tell you: which of your numbers the conversation came in on. There’s no page id or WhatsApp Business Account id in it. With a single number that doesn’t matter; if you run several numbers on different Facebook Pages, you’ll need to map that on your side.

Which Connection This Works On

This works on the official WhatsApp API connection only. Meta only delivers the structured referral information (including ctwa_clid) through the official WhatsApp Business API. The non-official WhatsApp (web) connection does not receive it — there’s no ad click data available on that connection, by design of how it works.

So if closed-loop ad attribution matters to you, run your Click-to-WhatsApp campaigns through a number connected via the official WhatsApp API.

First-Touch Behavior

The referral is captured on the first message a contact sends from an ad. If the same contact later clicks a different ad and that newer click carries a click identifier, the stored ad_referral is refreshed so the click id stays current for reporting. Organic post referrals (which have no ctwa_clid) never overwrite a previously captured paid-ad click id.

Getting the Data into Meta or Google Ads

Your AI Connector captures the attribution data and exposes it, but it does not push conversions to Meta or Google for you natively today. You forward the data using webhooks plus an automation tool.

The ad_referral object is included in the contact section of the outbound webhook events (for example New Message, Contact Resumed, Contact Tags Updated, and analytics events such as Appointment Booked).

A typical closed-loop setup:

  1. A lead clicks your Click-to-WhatsApp ad and messages you. Your AI Connector records ad_referral (including ctwa_clid) on the contact.
  2. As the lead progresses — booked a call, became a customer, was lost — you mark that outcome (see “Carrying the funnel stage” below).
  3. A webhook fires to your automation tool (Zapier, Make, or Pabbly) carrying both the outcome and the contact’s ctwa_clid.
  4. Your automation tool calls Meta’s Conversions API (using action_source = business_messaging and the ctwa_clid) or Google Ads (Offline Conversion Import / Enhanced Conversions for Leads) to report the conversion.

This way Meta and Google learn which ads produced real results and optimize toward them.

Carrying the Funnel Stage

To report a conversion you usually need two things: the click id (captured automatically) and the outcome (which you set). The most reliable way to attach an outcome is with tags, because applying a tag fires the contact_tags_updated webhook — and that payload includes the contact’s ad_referral. (Removing a tag does not fire it; see Contact Tags Updated.)

You can apply tags automatically:

  • Let your AI Agent tag the contact during the conversation — set up auto-tagging rules in the agent’s configuration. This is how the “one landing page per ad → one entry message → one tag” pattern works if you want to label the source yourself.
  • Or tag manually from Chats or the Contacts page.

Whenever a relevant tag changes, the webhook fires with the click id attached, ready to forward as a conversion.

The webhook URL is set on the tag itself, in the Tags tab of the agent (or campaign) the contact belongs to — not in Settings. Each tag gets its own URL, and they can all point at the same endpoint if you want one place to receive everything.

Reading a click id you already missed

ad_referral is also returned by the API on both GET /v1/contacts/{id} (as adReferral) and the contact list endpoint (as ad_referral), so if your receiver was down, or you’re reconciling after the fact, you can read the click id back instead of waiting for the next webhook. Contacts that arrived before the click id was recorded on them have null here — the value can only be captured from the incoming message itself, so there’s nothing to fill in retroactively.

Limitations

  • Official WhatsApp API connection only (not the non-official web connection).
  • No native, one-click Meta CAPI or Google Ads integration yet — you forward the data through Zapier/Make/Pabbly. If you’d like a native integration, let support know at hi@youraiconnector.com.
  • Attribution is captured going forward, from the moment this is live. It cannot be backfilled onto conversations that happened before.

Next Steps