Conversions API for Business Messaging(CAPI)

1. 1

   Connect a dataset to the WhatsApp Business Account

   In Events Manager (or through your provider), create or find the dataset linked to the WABA and note its ID. Use a system user access token with the whatsapp_business_manage_events permission.

2. 2

   Store the click ID when the chat starts

   From the first inbound message of an ad chat, save referral.ctwa_clid and source_id against the contact, keyed by the message wamid. Some placements, such as ads shown in WhatsApp Status, can arrive without a ctwa_clid, so treat it as optional.

3. 3

   Map business outcomes to events

   Decide which moments count: a qualified lead (LeadSubmitted), a paid order (Purchase) and so on. Fire on the confirmed outcome — the payment, not the cart.

4. 4

   Send the event

   POST to /{DATASET_ID}/events with action_source business_messaging, messaging_channel whatsapp, the WABA ID and ctwa_clid in user_data, and currency and value in custom_data.

5. 5

   Check it landed and do not repeat it

   A 200 response with events_received confirms receipt. Record which outcomes were sent so retries and duplicate webhooks never report the same order twice, then watch the results in Events Manager and Ads Manager.

Endpoint

POST /{DATASET_ID}/events

action_source

business_messaging

messaging_channel

whatsapp

user_data

whatsapp_business_account_id + ctwa_clid

Common events

Purchase, LeadSubmitted

event_time

Unix seconds, not milliseconds

Permission

whatsapp_business_manage_events

Success response

200 with events_received

Without conversion events, Click-to-WhatsApp campaigns can only be judged and optimised on conversations started — a cheap chat counts the same as one that became a 50,000-rupee order. Reporting leads and purchases with the click ID lets marketers running WhatsApp lead generation campaigns see cost per lead, conversion rate and return on ad spend in Ads Manager, and lets Meta's delivery system find more people like the ones who bought rather than the ones who only tapped. For developers it is a small integration — store one ID, send one POST — with an outsized effect on ad performance.

• Not storing ctwa_clid on the first message

  The click ID appears only in the referral object of the message the customer sends from the ad. If it is not saved then, the later purchase cannot be tied to the ad.

• Sending web-pixel style user data

  Business messaging events are matched by ctwa_clid and the WABA ID, not by hashed emails or browser cookies. Copying a website CAPI payload with action_source: website reports the wrong kind of event.

• Reporting the same order twice

  Payment webhooks and job retries repeat. Without a record of which orders were sent, one sale becomes two purchases and inflates return on ad spend. Claim each order before sending.

• Sending events late or with the wrong clock

  event_time must be Unix seconds; milliseconds put the event far in the future. The Conversions API rejects events that are too old (seven days for most action sources), so send as soon as the outcome is confirmed.

• Send the confirmed outcome (payment received, lead qualified), not intermediate clicks.
• Keep ctwa_clid optional in your schema — chats from some ad placements, such as WhatsApp Status ads, can arrive without one.
• Log the fbtrace_id of every failed call for Meta support.
• Compare purchases in Ads Manager with your own orders weekly to catch dropped or duplicated events.

What is the Conversions API for Business Messaging?

It is Meta's server API for reporting outcomes such as purchases and leads from chats that started with a Click-to-WhatsApp ad. Events carry the ad's click ID, ctwa_clid, so Meta can credit the right ad.

Where do I get the ctwa_clid?

From the webhook referral object on the customer's first message from the ad. It sits at messages[].referral.ctwa_clid; store it with the contact, because it is not repeated later in the conversation.

Is the Conversions API for Business Messaging the same as the Meta pixel?

No. The pixel runs in a website visitor's browser. The Conversions API for Business Messaging is called from your server with action_source business_messaging and the chat's click ID, so it works for sales closed inside WhatsApp.

Which events should I send from WhatsApp chats?

Send the outcomes you want ads optimised for, typically LeadSubmitted for qualified leads and Purchase for paid orders. Send each once, when it is confirmed, with the value and currency for purchases.