# 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](../get-started/creating-contacts.md) 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](webhooks.md) 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](webhooks.md#contact-tags-updated-webhook).) 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 - [Webhooks](webhooks.md) — see the full payload and which events include `ad_referral`. - [Using Tags to Label Contacts](../get-started/creating-tags.md) — set up the tags that carry your funnel stages.