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

Running ads to a page on your own website with a WhatsApp button instead? See Ad click attribution for WhatsApp.

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:

You can see it without any setup: the contact’s page shows a Came from ad label under their name (hover it for the ad details), the contact panel next to the chat shows it too, and the contact’s Activity starts with the ad tap. You can also read it through webhooks and the API (see below). It isn’t a column 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.

Leads That Arrive Without a Phone Number #

Some people who message you from an ad have their phone number hidden by WhatsApp. In that case Meta hands over a private id for the person instead of a number, and the contact is created with an empty phone field. That is expected. Replies, AI answers and automatic follow-ups still reach the person, because Your AI Connector addresses them through that id.

Leave the phone field empty on such a contact. Do not type your own business number into it: a message cannot be sent from a number to itself, so the next automatic follow-up would fail and the contact would be paused. Your AI Connector now refuses to save one of your own connected numbers as a contact’s phone. If the person later shares their number, or messages you again with it visible, it is filled in automatically.

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.

Click-to-Instagram and Click-to-Messenger Ads #

Ads that open an Instagram DM or a Messenger chat are recorded the same way, on the Facebook Page and Instagram account you connected with the Instagram & Messenger card. When someone starts a chat from one of those ads, the contact gets an ad_referral with channel set to instagram or messenger, source_type set to ad and source_id set to the ad ID. That gives you the ad behind each contact, so you can work out cost per booking per ad.

A few differences from WhatsApp:

• There is no ctwa_clid; that field is empty. Meta only issues that click identifier for WhatsApp.
• headline is the ad’s title when Meta sends it, and source_url is the ad’s image or video link when there is one. body is empty.
• If the contact first came from one ad and later starts a chat from a different ad, ad_referral shows the newer ad.
• Messenger ad contacts carry the ad from October 14, 2026 on. Contacts who came from a Messenger ad before that date have no ad_referral, because the ad details were not recorded then and cannot be filled in afterwards.
• Messenger chats that start with a tap on the Page’s Get Started button are not recorded. Remove the Get Started button from your Page (Meta Business Suite, Inbox settings) so people start the chat by typing, and the ad is recorded on their first message.

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. For ads that send people to your own website first, Your AI Connector can send results to Meta for you when a tag is applied: see Send results to Meta. For Click-to-WhatsApp ads 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 editor of the AI agent the contact is assigned 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).
• The built-in Send results to Meta sends the click data recorded by the website script; it does not send the ctwa_clid of Click-to-WhatsApp ads. For those, and for Google Ads, 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 — see the full payload and which events include ad_referral.
• Using Tags to Label Contacts — set up the tags that carry your funnel stages.
• Ad click attribution for WhatsApp: match clicks on ads that lead to your own website to the WhatsApp conversation.