Ad Attribution

When a customer taps a Click-to-WhatsApp ad (or a boosted post) and messages you, WhatsApp attaches a referral to that message. It says which ad the customer came from, what the ad showed, and includes a unique click ID (ctwaClid). Wassist stores this referral and exposes it in three places:

Where	Field	What it holds
Messages	`referral`	The referral on this inbound message, or `null`
Conversations	`latestReferral`	The most recent referral in the conversation, or `null`
Webhooks	`message.referral` and `latestReferral`	The same two values, on every inbound message event

WhatsApp only attaches the referral to the message the customer sends straight from the ad. latestReferral lets you attribute the rest of the conversation to that ad too, including later messages, orders and handoffs.

The referral object

{
  "messageId": "7f0c2a4e-...",
  "sourceType": "ad",
  "sourceId": "120210000000000000",
  "sourceUrl": "https://fb.me/abc123",
  "headline": "Summer sale — 20% off",
  "body": "Chat with us to find your size",
  "mediaType": "image",
  "imageUrl": "https://scontent.xx.fbcdn.net/...",
  "videoUrl": null,
  "thumbnailUrl": null,
  "ctwaClid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a",
  "welcomeMessage": "Hi! How can we help?",
  "createdAt": "2026-09-22T16:48:00Z"
}

Field	Description
`messageId`	The Wassist message the referral arrived on.
`sourceType`	`ad` or `post`.
`sourceId`	The Meta ad ID (or post ID). Use it to group conversations by ad.
`sourceUrl`	Link to the ad or post the customer tapped.
`headline`, `body`	The ad’s headline and body text.
`mediaType`	`image` or `video`.
`imageUrl`, `videoUrl`, `thumbnailUrl`	The ad creative. These are Meta CDN links and can expire, so copy the file if you need to keep it.
`ctwaClid`	The Click-to-WhatsApp click ID. Send it to Meta’s Conversions API (see below).
`welcomeMessage`	The pre-filled welcome message configured on the ad, when WhatsApp includes it.
`createdAt`	When the customer sent the message from the ad.

Every field except messageId and createdAt can be null. WhatsApp only sends the fields that apply to the ad.

Finding conversations from an ad

The list conversations endpoint accepts three filters:

Filter	Returns
`hasReferral=true` / `false`	Conversations that did / didn’t receive an ad referral
`referralSourceId=<ad id>`	Conversations with any referral from this ad or post
`ctwaClid=<click id>`	The conversation that contains this click

referralSourceId and ctwaClid match any referral in the conversation, not just the latest one.

curl "https://backend.wassist.app/api/v1/conversations/?referralSourceId=120210000000000000" \
  -H "X-API-Key: $WASSIST_API_KEY"

import { Wassist } from '@wassist/sdk';

const wassist = new Wassist({ apiKey: process.env.WASSIST_API_KEY! });

for await (const conversation of wassist.conversations.list({ referralSourceId: '120210000000000000' })) {
  console.log(conversation.contact.phoneNumber, conversation.latestReferral?.headline);
}

Reacting in real time

Every message.received and subscription.message.received webhook carries message.referral and latestReferral. That means your service can tag the lead or route it to a sales queue as soon as the first message arrives:

import type { WassistEvent } from '@wassist/sdk';

function handle(event: WassistEvent) {
  if (event.event !== 'message.received') return;

  const referral = event.message.referral;
  if (referral?.sourceType === 'ad') {
    // First message straight from an ad: create the lead.
    createLead({
      phone: event.contact.phoneNumber,
      adId: referral.sourceId,
      clickId: referral.ctwaClid,
    });
  }
}

Sending conversions back to Meta

Send ctwaClid to Meta’s Conversions API for Business Messaging when a WhatsApp conversation turns into a lead or a purchase. Meta then credits the conversion to the ad in Ads Manager and uses it to optimise delivery.

curl -X POST "https://graph.facebook.com/v21.0/$DATASET_ID/events?access_token=$META_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [{
      "event_name": "Purchase",
      "event_time": 1766000000,
      "action_source": "business_messaging",
      "messaging_channel": "whatsapp",
      "user_data": {
        "whatsapp_business_account_id": "<your WABA id>",
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-..."
      },
      "custom_data": { "currency": "GBP", "value": 49.99 }
    }]
  }'

The dataset ID, access token and required fields come from your Meta Business setup. Check Meta’s Conversions API documentation for the current payload.

Existing conversations

Referrals are also available for messages received before this feature launched, so historical ad-driven conversations show a latestReferral too. welcomeMessage is usually null on these older messages because it wasn’t stored at the time. The click ID and ad details are filled in.

What’s Next

Webhooks

Receive message.received events with the referral attached.

Conversation Routing

Send ad-driven conversations to your own service instead of the agent.

Create Your Agent

WhatsApp Setup

Advanced Features

Webhooks

Developer Tools

The referral object

Finding conversations from an ad

Reacting in real time

Sending conversions back to Meta

Existing conversations

What’s Next

Webhooks

Conversation Routing

​The referral object

​Finding conversations from an ad

​Reacting in real time

​Sending conversions back to Meta

​Existing conversations

​What’s Next

Webhooks

Conversation Routing

The referral object

Finding conversations from an ad

Reacting in real time

Sending conversions back to Meta

Existing conversations

What’s Next