Ad Referral

When a contact opens a chat by clicking a Click-to-WhatsApp ad on Facebook or Instagram, their first message carries the ad it came from. WSAPI exposes that as an adReferral object inside the message event.

What arrives

{
  "eventType": "message",
  "eventData": {
    "id": "3EB0C767D82B2D3F1B1A",
    "chatId": "5491100000000@s.whatsapp.net",
    "sender": {
      "id": "5491100000000@s.whatsapp.net",
      "phone": "5491100000000",
      "lid": "102030405060708",
      "isMe": false
    },
    "type": "text",
    "text": "Hi, I saw your ad — is it still available?",
    "adReferral": {
      "ctwaClid": "ARAkLkA8rmlFeiCktEJQ7QTwRiyYHAFDLMNDBH0CD3qpjd0HR4i",
      "sourceType": "ad",
      "sourceId": "120210000000000000",
      "sourceUrl": "https://fb.me/1aBcDeFgH",
      "sourceApp": "facebook",
      "title": "Summer sale — 2x1",
      "body": "Message us for a quote",
      "mediaType": "image",
      "thumbnailUrl": "https://scontent.example/ad-thumb.jpg",
      "conversionSource": "ctwa_ad",
      "showAdAttribution": true
    }
  }
}

Field	Description
`ctwaClid`	Click identifier of the ad click, used by Meta’s Conversions API for attribution
`sourceType`	What the contact clicked — typically `ad` or `post`
`sourceId`	Identifier of the ad or post
`sourceUrl`	URL of the ad or post
`sourceApp`	Originating Meta app — `facebook` or `instagram`
`title`	Headline of the ad, as shown in the chat
`body`	Body text of the ad, as shown in the chat
`mediaType`	Media type of the ad creative — `image` or `video`
`thumbnailUrl`	URL of the ad creative thumbnail
`conversionSource`	Entry point reported by WhatsApp, e.g. `ctwa_ad`
`showAdAttribution`	Whether WhatsApp shows the ad attribution banner on the message

How it behaves

Only the first message carries ctwaClid. Later messages from the same contact do not. WSAPI does not store message payloads, so it cannot be recovered afterwards — persist it when it arrives.
Fields are passed through from WhatsApp unchanged, and any of them may be absent. What arrives depends on the ad format and on the contact’s WhatsApp client. Treat every field as optional.
Any message type can carry it. If the contact’s first message is an image or a document rather than text, adReferral is projected the same way.
It is only present when there is ad attribution. Businesses send rich link-preview cards over the same underlying WhatsApp field, and those do not produce an adReferral.
It arrives inside the message event, so message has to be allowed in your event filters.

What you do with ctwaClid — reporting conversions to Meta’s Conversions API, for example — happens on your side. See Meta’s Conversions API documentation.

Overview

Events

Reference

What arrives

How it behaves

​What arrives

​How it behaves

What arrives

How it behaves