Why Is ctwa_clid Missing? Every Cause, Explained

ByBNW Staff

You ran a Click to WhatsApp ad and made a sale, but your webhook shows ctwa_clid missing. Without that click ID, Meta cannot link the purchase to the ad. This guide walks through every cause and the fix for each one.

Direct Answer:

A ctwa_clid missing from your webhook usually has a documented cause. The chat may not have come from a Click to WhatsApp ad, or the ad ran in WhatsApp Status. Otherwise, the number is not on Meta’s API, or your code dropped the value. To test the event you send back to Meta, you can paste the payload into the free CAPI debugger, which runs in your browser.

What ctwa_clid Is and Where Meta Sends It

ctwa_clid is the Click to WhatsApp ad click ID. It is the one value that ties a WhatsApp conversation to a specific ad click.

Meta delivers it inside the referral object of an incoming message in the messages webhook. Meta’s reference says the referral object is “only included if message sent via a Click to WhatsApp ad.”

The referral object can include these fields:

  •     source_id: the ad ID
  •     source_url: the ad URL
  •     source_type: shown as “ad” in Meta’s examples
  •     headline and body: the ad’s headline and primary text
  •     media_type: image or video, with matching media URLs
  •     ctwa_clid: the click ID you need for attribution

You then send ctwa_clid back through the Conversions API. Set action_source to business_messaging and messaging_channel to whatsapp.

Documented Causes of a ctwa_clid Missing Error

These causes come directly from Meta’s developer documentation. Check them first, because no code change will fix them.

1. The Chat Did Not Start From a Click to WhatsApp Ad

No ad click means no referral object. Customers who find your number on a website, a QR code, or a saved contact never generate one.

Meta’s examples show that a “Message business” button sends a context object instead. If the raw webhook has no referral object, the chat was not ad-driven.

2. The Ad Ran in WhatsApp Status

Meta states that “the ctwa_clid property is omitted entirely for messages originating from an ad in WhatsApp Status.” You may still get other referral fields.

So a referral object with ctwa_clid missing can be expected behavior. Check the ad’s placements using the source_id before you debug any code.

3. The Number Only Uses the WhatsApp Business App

ctwa_clid arrives through a webhook, and webhooks belong to the WhatsApp Business Platform. That means the Cloud API or the older On-Premises API.

A number used only in the WhatsApp Business app has no webhook, so nothing carries the click ID to your system. Meta does let you connect an existing app number to the Cloud API, a setup often called Coexistence. Before you rely on it for ad attribution, check Meta’s current Coexistence documentation to see what it covers.

4. You Are Still on the Old On-Premises API

The On-Premises API is the older, self-hosted way to run the WhatsApp Business API. Meta’s last supported client for it expired on October 23, 2025, so any setup still running it is unsupported now.

Older On-Premises builds may also leave ctwa_clid out, but there is little point chasing version numbers on a product Meta no longer supports. If your webhook comes from one, move to the Cloud API and test again.

Code and Setup Mistakes That Drop ctwa_clid

If Meta sends the value but your database never stores it, the fault sits in your own stack. These are the places to look.

5. Your Parser Reads the Wrong Part of the Payload

ctwa_clid lives under messages, then referral, in the webhook value object. It is not in the contacts array, the metadata block, or status webhooks.

A parser that only extracts message text will skip it. Meta does not say whether referral repeats on later messages, so store ctwa_clid the first time it appears.

6. A Middleware Layer Does Not Pass It Through

Webhooks often pass through a provider, an automation platform, or a custom relay. Every layer must forward the full referral object.

Some integrations only map sender and text fields. Public issue trackers show cases where the referral object reached one system but never the next.

7. The Connection Does Not Use Meta’s Official API

Some tools link WhatsApp by scanning a QR code with a phone. These connections do not receive Meta’s webhooks, so they never see the referral object.

If ad attribution matters, connect the number through Meta’s WhatsApp Business Platform.

8. The Value Was Changed Before Sending

Sometimes ctwa_clid exists but arrives at Meta damaged. Watch for these mistakes:

  •     Hashing it: SHA-256 hashing applies to customer information like email and phone, not to ctwa_clid.
  •     Adding spaces or quotes: string handling errors can quietly change the value.
  •     Truncating it: a database column that is too short can cut it off.

Treat ctwa_clid as an opaque ID. Store it exactly as received and send it back unchanged.

Causes Reported by Developers but Not Confirmed by Meta

On Meta’s developer community, some developers report ctwa_clid missing even when a referral object arrives. Meta has not confirmed these causes.

Explanations shared in those threads include:

  •     The customer opened the chat in a web browser, not the mobile app.
  •     The customer tapped an organic post instead of the paid ad.
  •     The customer dismissed the ad context before messaging.
  •     The ad content was removed before the customer messaged.

Treat these as leads to investigate, not as rules. No official fix was confirmed in those threads.

What a Missing ctwa_clid Affects

Without ctwa_clid, a Purchase or LeadSubmitted event has no click ID to match on. Meta cannot credit that conversion to the right ad.

That affects optimization too. Meta says purchase optimization is available for ads that click to WhatsApp, and it depends on conversion events.

How much data you lose depends on these factors:

  •     Placement mix: more Status placements mean more chats without a click ID.
  •     Integration type: app-only numbers and unofficial connections lose the value completely.
  •     Data handling: each relay or transformation adds a chance to drop it.

What to Send When There Is No Click ID

Meta offers a fallback path for some WhatsApp events. Instead of ctwa_clid, you send hashed customer information.

Meta sets clear conditions for this path:

  •     page_id is required: an event without page_id “is rejected even when it carries valid customer information.”
  •     Short lookback: it attributes events to ad interactions from the past seven days.
  •     Limited reach: it is available in a subset of countries.
  •     No guarantee: matching is not guaranteed.

The fallback helps, but a valid click ID is stronger. Fix the cause upstream whenever you can.

Checklist: How to Fix ctwa_clid Missing in Your Webhook

  1.     Capture the raw webhook. Log it before any parsing or forwarding.
  2.     Look for a referral object. If it is absent, the chat did not come from a Click to WhatsApp ad.
  3.     Check the placement. A referral without ctwa_clid may point to a WhatsApp Status ad.
  4.     Confirm your integration. Use the Cloud API, since Meta’s last On-Premises client has expired.
  5.     Trace every relay. Compare the raw referral object with what your system stores.
  6.     Protect the value. Store and send ctwa_clid exactly as received.
  7.     Set up the fallback. Where eligible, send hashed customer information with page_id.

Frequently Asked Questions

What is ctwa_clid?

ctwa_clid is the Click to WhatsApp ad click ID. Meta sends it in the messages webhook so you can tie a WhatsApp conversation to the ad click that started it.

Where is ctwa_clid in the WhatsApp webhook?

It sits inside the referral object of an incoming message, under messages in the webhook value object. It does not appear in the contacts array or in status webhooks.

Why is ctwa_clid missing for WhatsApp Status ads?

Meta omits ctwa_clid entirely for messages that come from an ad in WhatsApp Status. You may still receive other referral fields, but the click ID is not sent.

Does the WhatsApp Business app provide ctwa_clid?

No. A number used only in the WhatsApp Business app has no webhook. To receive ctwa_clid, the number must be connected to the Cloud API, which Meta supports for existing app numbers.

Does the old On-Premises API still send ctwa_clid?

You should not build on it. Meta’s final On-Premises API client expired on October 23, 2025, so move to the Cloud API, where ctwa_clid arrives in the referral object of the messages webhook.

Should I hash ctwa_clid before sending it?

No need. Hashing is for customer details like email and phone. Meta’s sample sends ctwa_clid as a plain string, so send it exactly as you received it.

Is ctwa_clid sent when a chat starts from a Message business button?

No. Meta’s examples show these messages carry a context object instead of a referral object. Only messages sent via a Click to WhatsApp ad include the referral object.

What action_source should WhatsApp Conversions API events use?

Set action_source to business_messaging and messaging_channel to whatsapp. In user_data, Meta’s sample pairs ctwa_clid with your whatsapp_business_account_id.

Which events can I send for business messaging?

Meta lists events such as Purchase, LeadSubmitted, InitiateCheckout, AddToCart, ViewContent, QualifiedLead, and several order status events like OrderShipped and OrderDelivered.

Can I send a WhatsApp event when ctwa_clid is missing?

In some cases, yes. You can send hashed customer information with page_id. Meta limits this path to a seven-day lookback and a subset of countries, and matching is not guaranteed.

Which permissions does WhatsApp conversion reporting need?

Meta lists whatsapp_business_management and whatsapp_business_manage_events. Its setup page puts both under advanced access and tells you to apply for advanced access for whatsapp_business_manage_events.

Do Messenger and Instagram events use ctwa_clid?

No. Meta’s samples match Messenger events with page_id and page_scoped_user_id. Instagram events use instagram_business_account_id and the Instagram scoped ID.

Conclusion

Most cases of ctwa_clid missing trace back to Meta’s own rules. Non-ad chats, Status ads, app-only numbers, and old On-Premises versions explain the gap without any bug.

If none of those apply, follow the value through your stack. Log the raw webhook, check each relay, and send the ID back unchanged to fix ctwa_clid missing for good.