> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wassist.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Ad Attribution

> See which Click-to-WhatsApp ad started a conversation, and send the click ID back to Meta.

When a customer taps a [Click-to-WhatsApp ad](https://www.facebook.com/business/help/447934475640650) (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](/api-reference/conversations/messages/list) | `referral`                              | The referral on this inbound message, or `null`         |
| [Conversations](/api-reference/conversations/get)      | `latestReferral`                        | The most recent referral in the conversation, or `null` |
| [Webhooks](/concepts/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

```json theme={null}
{
  "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](/api-reference/conversations/list) 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://backend.wassist.app/api/v1/conversations/?referralSourceId=120210000000000000" \
    -H "X-API-Key: $WASSIST_API_KEY"
  ```

  ```typescript SDK theme={null}
  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);
  }
  ```
</CodeGroup>

## 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:

```typescript theme={null}
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](https://developers.facebook.com/docs/marketing-api/conversions-api/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.

```bash theme={null}
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 }
    }]
  }'
```

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

## 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

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/concepts/webhooks">
    Receive `message.received` events with the referral attached.
  </Card>

  <Card title="Conversation Routing" icon="route" href="/guides/webhooks/routing">
    Send ad-driven conversations to your own service instead of the agent.
  </Card>
</CardGroup>