Whatsable
When someone clicks a Click-to-WhatsApp ad on Facebook or Instagram and messages you, Meta attaches a referral object to that first inbound. That object is the only direct link between your ad spend and the WhatsApp conversation that follows. Once you miss it, it is gone.
This article covers what the referral contains, how to persist the two fields that matter most, how to label the contact automatically, and how to close the attribution loop by sending the click ID back to Meta's Conversions API.
WhatsAble does not create the ad. WhatsAble does not persist the referral for you. Both of those are your responsibility.
---
What the referral contains
The referral object arrives top-level on your payload, regardless of whether your destination is a custom webhook, n8n, Zapier, or Make. The full field reference is in the table below.
| Field | Description | When present |
|---|---|---|
| `referral` | Container for Click-to-WhatsApp or post attribution | First inbound from a CTWA ad or post; absent on ordinary chat and most follow-ups |
| `referral.source_type` | `ad` or `post` | With referral |
| `referral.source_id` | Meta ad or post ID | With referral. Persist this |
| `referral.source_url` | Ad or post URL | With referral |
| `referral.headline` | Ad or post headline | With referral |
| `referral.body` | Ad or post body copy | With referral |
| `referral.media_type` | `image` or `video` | With referral |
| `referral.image_url` | Image creative URL | When `media_type` is `image` (URLs can expire) |
| `referral.video_url` | Video creative URL | When `media_type` is `video` |
| `referral.thumbnail_url` | Video thumbnail URL | Video creatives |
| `referral.ctwa_clid` | Click ID for Meta Conversions API | Usually with ad referral; Status ads may omit it. Persist this |
| `referral.welcome_message` | Optional object. Welcome message when Meta includes it | Optional; nested child keys are unverified. Do not invent them |
---
When is the referral present?
| Situation | Referral present? |
|---|---|
| First inbound after an ad or post tap | Yes, typically |
| Later messages in the same chat | Usually absent. Persist immediately |
| Ordinary WhatsApp chat | Absent |
| WhatsApp Status ads | Referral may be present; `ctwa_clid` may be omitted |
The first message is the window. Most chats lose the referral on the second message. There is no second chance once the contact replies again, so your automation needs to write these values before it does anything else.
---
Step 1: Catch and persist `ctwa_clid` and `source_id`
In your WhatsAble dashboard, go to Developer and add an endpoint URL. Turn incoming on. When the first Click-to-WhatsApp message arrives at that endpoint, the payload will carry the full referral object.
Your automation should do three things, in order:
- Read `referral.ctwa_clid` and `referral.source_id` from the payload.
- Write both values to a Google Sheet row, a CRM contact record, or a database column, keyed to the contact's phone number.
- Not wait. Do not check for a second message or a reply before writing. The window is this first POST.
The same flow works across all four destinations supported here:
Custom webhook. Your server receives each incoming POST. Read the referral fields from the JSON body and write to your Sheet or CRM before you do anything else with the event.
n8n. The trigger node fires on each inbound message. Map referral.ctwa_clid and referral.source_id in the first node of your scenario and route them to a Google Sheets node or an HTTP request to your CRM. If your contacts live in Pipedrive or Monday, you can create a deal or item in the same workflow and attach both fields there.
Make. Same shape: the trigger module delivers the inbound, you map both referral fields and write them to a Google Sheets row. Pipedrive and Monday modules in the same scenario can receive the values in the same run.
Zapier. Trigger on the inbound, map referral.ctwa_clid and referral.source_id, and append them to a Sheet row or create a CRM record in the same Zap.
---
Step 2: Mark the chat with a custom label you create
Labels help you separate Click-to-WhatsApp chats from the rest of the inbox and update your Sheet later. Do not rely on a stock label named qualified. Create your own custom label, for example ctwa-lead or qualified as a name you chose.
A human can apply that label in the inbox. On Pro and Agency, an AI chatbot can apply labels when you say so in Custom Instructions, and ProactiveBot can manage labels. Once the label is on the chat, later message payloads can include a labels field.
Safe automation pattern: on a later message event (not a label change alone), filter when labels contains your custom label, then update the Google Sheet or CRM row you keyed on phone. Do not claim that applying a label with no new message fires your webhook. That label-only path is unverified.
---
Step 3: Send the click ID to Meta's Conversions API
Capturing the referral tells you which ad started the conversation. Sending a conversion event back to Meta tells Ads Manager whether that ad produced a result you care about. These are two separate steps and you own both of them.
When the contact reaches a meaningful stage, read the ctwa_clid you saved in step 1 and send a server-side event to the Meta Conversions API. You build this step yourself in Make, Zapier, or n8n. The required fields for a WhatsApp business messaging conversion event:
- action_source: business_messaging - messaging_channel: whatsapp - ctwa_clid: the value you persisted from the first inbound
You also need a Meta dataset ID and a system user access token from Business Manager. WhatsAble does not send this event; the call goes from your automation tool to Meta's API directly.
A three-step Make scenario covers it: a trigger (a new Sheet row, a form submission, or a Pipedrive deal moving to a stage you define), a step that retrieves the saved ctwa_clid for that phone number, and an HTTP module that posts the conversion event to the CAPI endpoint. n8n and Zapier follow the same three-step shape with different node names.
---
What you end up with
After these three steps are working:
- Your Sheet or CRM contains ctwa_clid and source_id for each WhatsApp contact who arrived from an ad, written at the moment of first message. - A custom label you create marks those chats in the inbox so you can filter them, and later message events that carry labels can update your Sheet. - Ads Manager receives server-side conversion events that close the attribution loop from the original ad click to a real business outcome, not just a WhatsApp session that opened and went silent.
The referral object is what connects Meta's ad data to your WhatsApp inbox. Persisting it on the first inbound, labeling the contact, and returning the click ID to CAPI are the three moves. None of them require custom code. Any of your usual automation tools can run all three in a single workflow.
