Does every message in a Click-to-WhatsApp chat include the referral?

No, it comes on the message the customer sends from the ad. Later messages typed in the same chat do not carry it, so save it with the contact and conversation the first time it appears.

What is ctwa_clid used for?

It is the click ID for that ad interaction. Send it with conversion events to the Conversions API for Business Messaging so Meta can attribute purchases or leads to the ad that started the chat.

Why is ctwa_clid missing from some referrals?

Meta omits it for chats that start from an ad in WhatsApp Status. The rest of the referral, such as `source_id` and `headline`, is still there, so fall back to the ad ID for campaign reporting.

Are chats from Click-to-WhatsApp ads cheaper to answer?

Often, yes: they can open a 72-hour free entry point window. It applies when the customer messaged from the Android or iOS app and you reply within 24 hours; status webhooks then report `type` `free_entry_point`.

Is the referral object the same as UTM parameters?

No, UTM parameters tag website links you build yourself. The referral is data Meta attaches to the WhatsApp message, describing the ad the customer tapped, and needs no tagging on your side.

WhatsApp Referral Object: CTWA Ad Attribution

01 · Definition

What is the webhook referral object?

The webhook referral object is a block Meta adds to an inbound message in the messages webhook when the customer started the chat from a Click-to-WhatsApp ad. It sits inside the message itself — in the webhook payload at entry[].changes[].value.messages[].referral, next to from, id, type and the content — and Meta includes it only when the message was sent via a Click-to-WhatsApp ad.

Its fields describe the ad: source_url and source_id (the ad's URL and ID), source_type (ad), headline and body (the ad's headline and primary text), media_type (image or video) with image_url, or video_url and thumbnail_url, the ad's greeting under welcome_message.text, and ctwa_clid — the click ID that ties this conversation to that ad click. Meta omits ctwa_clid for messages that start from an ad shown in WhatsApp Status.

The referral is attribution data, and you get it on the message the customer sends from the ad — not on everything they type later in the thread — so capture it with the contact and conversation the moment it arrives. This differs from the Click-to-WhatsApp ads page, which covers creating and running the ads: the referral object is what those ads hand to your systems, and ctwa_clid is the key the Conversions API for Business Messaging uses to report outcomes back against the ad.

Key takeaways

The referral object is ad data Meta attaches to an inbound WhatsApp message sent from a Click-to-WhatsApp ad.
It carries source_id, source_url, headline, body, the ad's media URLs, welcome_message and the ctwa_clid click ID.
Meta omits ctwa_clid when the chat starts from an ad in WhatsApp Status, so store it as optional.
Save the referral the moment it arrives, keyed by wamid: the rest of the thread does not repeat it.
Send ctwa_clid with Conversions API events so Meta can attribute leads and purchases to the ad.

See InfiQ pricing

02 · Specifications

The webhook referral object: key facts and limits

Location	messages[].referral on the inbound message
Present when	The message was sent from a Click-to-WhatsApp ad
Ad identity	source_id, source_url, source_type (ad)
Creative	headline, body, media_type (image or video), media URLs
Click ID	ctwa_clid — omitted for ads in WhatsApp Status
Greeting	welcome_message.text
Reporting back	Conversions API, action_source business_messaging

03 · Code samples

The webhook referral object in code

1{
2  "from": "919812345678",
3  "id": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAEhgUM0VCMDQ2QTdC",
4  "timestamp": "1760860800",
5  "type": "text",
6  "text": { "body": "Hi, I want details about the NEET crash course" },
7  "referral": {
8    "source_url": "{AD_URL}",
9    "source_id": "120211234567890123",
10    "source_type": "ad",
11    "body": "Crash course starts 3 November. Limited seats.",
12    "headline": "NEET 2027 crash course",
13    "media_type": "image",
14    "image_url": "{AD_IMAGE_URL}",
15    "ctwa_clid": "{CTWA_CLID}",
16    "welcome_message": { "text": "Hi! Ask us anything about admissions." }
17  }
18}

The message object inside value.messages. Illustrative values; Meta fills the URLs and click ID.

04Playground

A working model of Webhook Referral Object. Use its controls to replay it step by step.

Where do ad taps turn into attributed sales?

5 / 5

65% drop-off · 7,800 people (illustrative) lost
7.1% drop-off · 300 people (illustrative) lost
66.7% drop-off · 2,600 people (illustrative) lost
76.2% drop-off · 990 people (illustrative) lost(biggest leak)

Stage 5 of 5

Enrolments reported back

310 people (illustrative)

23.8% of the previous stage made it here (76.2% drop-off, 990 people (illustrative) lost). That is 2.6% of the top.

Purchase events sent to the Conversions API with the stored ctwa_clid.

Top to bottom: 2.6%
Biggest leak: Qualified leads → Enrolments reported back (76.2%)

An illustrative admissions campaign from ad tap to reported enrolment. Step through each stage to see where the referral arrives, where ctwa_clid can go missing, and what is reported back.

05 · Operation

How does the webhook referral object work?

The customer taps the ad
A Click-to-WhatsApp ad on Facebook or Instagram opens a chat with the business, often with a prefilled message and a greeting from the ad.
Their message carries the referral
When the customer sends that message, the messages webhook includes a referral object inside it with source_id, source_url, the headline, the media and ctwa_clid.
Store it before anything else
Save source_id, ctwa_clid, headline and the received time against the contact and conversation, keyed by the message wamid so webhook retries cannot create duplicate leads.
Act on it
Route by source_id — a loan ad to the lending team, a festive offer to the sales bot — and shape the first reply around the ad's headline.
Report outcomes back
When the chat converts, send an event such as Purchase or LeadSubmitted to the Conversions API with action_source business_messaging, messaging_channel whatsapp and the stored ctwa_clid.

06 · Worked example: Which ad actually filled the seats

Example: Which ad actually filled the seats

A Lucknow coaching institute runs two Click-to-WhatsApp ads before admissions: one for a NEET crash course and one for weekend Class 10 tuition. Its webhook handler stores each new chat's source_id and ctwa_clid and sends NEET leads to a counsellor queue. After four weeks the CRM shows the NEET ad brought fewer chats but more paid enrolments, which are reported back as Purchase events carrying the click ID — so next month's budget moves to the ad that filled seats, not the one with the most taps.

07 · Rationale

Why does the webhook referral object matter?

Without the referral, every chat from a paid campaign looks like organic traffic, and marketers cannot say which ad produced which lead or order. Capturing it lets you tag conversations by campaign for campaign analytics, route ad leads to the right team, open the right bot flow for the ad's offer, and send purchase or lead events back to Meta with ctwa_clid so the campaign is measured on real outcomes rather than on taps. It also marks the chats that can open a free entry point window: when the customer wrote from the Android or iOS app and you reply within 24 hours, Meta does not charge for messages delivered in the following 72 hours.

08 · Cautions

Common mistakes with the webhook referral object

Not saving it on first sight
The referral rides on the message sent from the ad, not on the rest of the thread. If the handler skips it once, the attribution is gone — store it before any bot logic runs.
Middleware that drops unknown keys
Inboxes, queues and gateways that map Meta's payload to their own schema often discard referral. Check that the whole object survives every hop to your CRM.
Treating ctwa_clid as always present
Meta omits it for ads shown in WhatsApp Status. Make the column nullable and fall back to source_id for campaign reporting.
Reading the referral as marketing consent
A customer who messages you from an ad has started a conversation; that is not by itself a record of consent to future marketing templates. Capture opt-in explicitly.

09 · Recommended practice

Best practices for the webhook referral object

Store the whole referral as JSON beside the extracted columns — Meta adds fields over time.
Map source_id to readable campaign names nightly so sales teams see which ad a lead came from.
Send conversion events promptly, and only for interactions that happened in the WhatsApp thread.
Compare chats with a referral against Ads Manager link clicks to spot taps that never became messages.

10 · Questions and answers

Webhook Referral Object FAQs

Does every message in a Click-to-WhatsApp chat include the referral?: No, it comes on the message the customer sends from the ad. Later messages typed in the same chat do not carry it, so save it with the contact and conversation the first time it appears.
What is ctwa_clid used for?: It is the click ID for that ad interaction. Send it with conversion events to the Conversions API for Business Messaging so Meta can attribute purchases or leads to the ad that started the chat.
Why is ctwa_clid missing from some referrals?: Meta omits it for chats that start from an ad in WhatsApp Status. The rest of the referral, such as source_id and headline, is still there, so fall back to the ad ID for campaign reporting.
Are chats from Click-to-WhatsApp ads cheaper to answer?: Often, yes: they can open a 72-hour free entry point window. It applies when the customer messaged from the Android or iOS app and you reply within 24 hours; status webhooks then report type free_entry_point.
Is the referral object the same as UTM parameters?: No, UTM parameters tag website links you build yourself. The referral is data Meta attaches to the WhatsApp message, describing the ad the customer tapped, and needs no tagging on your side.

Webhook Referral Object

Properties

What is the webhook referral object?

The webhook referral object: key facts and limits

The webhook referral object in code

04Playground

Where do ad taps turn into attributed sales?

How does the webhook referral object work?

The customer taps the ad

Their message carries the referral

Store it before anything else

Act on it

Report outcomes back

Example: Which ad actually filled the seats

Why does the webhook referral object matter?

Common mistakes with the webhook referral object

Not saving it on first sight

Middleware that drops unknown keys

Treating ctwa_clid as always present

Reading the referral as marketing consent

Best practices for the webhook referral object

Webhook Referral Object FAQs

See how this works on InfiQ

Put Webhook Referral Object to work

See how this works on InfiQ