{"id":339,"date":"2026-10-25T13:07:49","date_gmt":"2026-10-25T13:07:49","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/meta-conversions-api-whatsapp\/"},"modified":"2026-10-25T13:07:52","modified_gmt":"2026-10-25T13:07:52","slug":"meta-conversions-api-whatsapp","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/en\/meta-conversions-api-whatsapp\/","title":{"rendered":"Meta Conversions API for WhatsApp: sending the sale back to your ads"},"content":{"rendered":"\n

Updated on October 25, 2026<\/em><\/p>\n\n\n\n

The Conversions API for Business Messaging is Meta’s official way to report that a conversation started by a Click-to-WhatsApp ad turned into a sale, a lead or another outcome. You capture the ctwa_clid<\/code> from the webhook, store it with the conversation and, when the event happens, send a POST<\/code> to the dataset of your WhatsApp Business account with action_source: \"business_messaging\"<\/code> and messaging_channel: \"whatsapp\"<\/code>. The event shows up in Events Manager and gets attributed to the ad.<\/p>\n\n\n\n

This guide covers the requirements, the step-by-step setup, the supported events, a Node.js example, and how to handle duplicates and personal data.<\/p>\n\n\n\n

Why send the sale back<\/h2>\n\n\n\n

Without this feedback, Meta only sees the top of the funnel: how many people clicked and started a conversation. The sale happens later, in the chat or at your checkout, and stays invisible to Ads Manager. With the Conversions API, you give Meta the real outcome of each click.<\/p>\n\n\n\n

The first step is having attribution in your own system: storing the webhook’s referral<\/code> and linking the order to the click. That’s covered in how to know which ad generated the sale<\/a>. This article picks up where that one ends.<\/p>\n\n\n\n

Requirements<\/h2>\n\n\n\n

Per the Conversions API for Business Messaging onboarding guide<\/a>, for Click-to-WhatsApp ads you need:<\/p>\n\n\n\n

Requirement<\/th>Detail<\/th><\/tr><\/thead>
Meta developer app<\/td>Created in the App Dashboard<\/td><\/tr>
whatsapp_business_management<\/code> permission<\/td>With advanced access<\/td><\/tr>
whatsapp_business_manage_events<\/code> permission<\/td>With advanced access; apps that already have advanced access to whatsapp_business_messaging<\/code> are approved automatically when they apply<\/td><\/tr>
Marketing API access level<\/td>The “Marketing API Access Tier” feature on the app<\/td><\/tr>
Cloud API integration<\/td>Hosted by Meta (the recommended option)<\/td><\/tr>
Token with both permissions<\/td>System user, business integration system user, or Embedded Signup token<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

To generate a token that doesn’t expire, see permanent token with a system user<\/a>.<\/p>\n\n\n\n

Step by step<\/h2>\n\n\n\n

1. Find your waba_id<\/h3>\n\n\n\n

It’s the WhatsApp Business account ID. You can find it in WhatsApp Manager and in the webhook, in the entry[].id<\/code> field.<\/p>\n\n\n\n

2. Create or retrieve the dataset<\/h3>\n\n\n\n

A dataset is where Meta collects events from different sources (website, app, physical store, chats). It’s owned by the business. A POST<\/code> to the WhatsApp Business account’s dataset endpoint creates one, or returns the existing one:<\/p>\n\n\n\n

curl -X POST \"https:\/\/graph.facebook.com\/v26.0\/WABA_ID\/dataset?access_token=TOKEN\"<\/code><\/pre>\n\n\n\n
A GET<\/code> on the same endpoint returns the existing dataset_id<\/code>. The response is an ID: store it, it’s where your events go.<\/p>\n\n\n\n
3. Capture the ctwa_clid<\/h3>\n\n\n\n
The ctwa_clid<\/code> arrives in the referral<\/code> object of the incoming message when the conversation starts from a Click-to-WhatsApp ad. Meta describes it as a personal identifier, unique per click, and recommends storing it with the conversation. It’s not included for ads shown in WhatsApp Status.<\/p>\n\n\n\n
4. Send the event<\/h3>\n\n\n\n
When the conversion happens, send it to \/{DATASET_ID}\/events<\/code>:<\/p>\n\n\n\n
curl -X POST \"https:\/\/graph.facebook.com\/v26.0\/DATASET_ID\/events?access_token=TOKEN\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"data\": [\n      {\n        \"event_name\": \"Purchase\",\n        \"event_time\": 1761400000,\n        \"action_source\": \"business_messaging\",\n        \"messaging_channel\": \"whatsapp\",\n        \"user_data\": {\n          \"whatsapp_business_account_id\": \"WABA_ID\",\n          \"ctwa_clid\": \"ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4...\"\n        },\n        \"custom_data\": {\n          \"currency\": \"BRL\",\n          \"value\": 297.00\n        }\n      }\n    ]\n  }'<\/code><\/pre>\n\n\n\n
event_time<\/code> is the conversion time in Unix seconds. The official example also includes partner_agent<\/code>, a field partners use to identify themselves; if you integrate directly without a partner, it doesn’t apply.<\/p>\n\n\n\n
5. Check Events Manager<\/h3>\n\n\n\n
After you send it, the event appears in Events Manager under the dataset. That’s where you confirm the integration is working.<\/p>\n\n\n\n
Supported events<\/h2>\n\n\n\n
According to the FAQ in the official guide, the Conversions API for Business Messaging supports:<\/p>\n\n\n\n
Event<\/th>When to use it<\/th><\/tr><\/thead>
Purchase<\/code><\/td>Payment confirmed<\/td><\/tr>
LeadSubmitted<\/code><\/td>Person sent the requested details (name, email, interest)<\/td><\/tr>
QualifiedLead<\/code><\/td>Lead qualified by your team or an AI agent<\/td><\/tr>
ViewContent<\/code><\/td>Person viewed a product or catalog in the chat<\/td><\/tr>
AddToCart<\/code><\/td>Item added to cart<\/td><\/tr>
InitiateCheckout<\/code><\/td>Payment link or PIX code generated (PIX is Brazil’s instant payment system)<\/td><\/tr>
CartAbandoned<\/code><\/td>Cart not completed<\/td><\/tr>
OrderCreated<\/code><\/td>Order created<\/td><\/tr>
OrderShipped<\/code><\/td>Order shipped<\/td><\/tr>
OrderDelivered<\/code><\/td>Order delivered<\/td><\/tr>
OrderCanceled<\/code><\/td>Order canceled<\/td><\/tr>
OrderReturned<\/code><\/td>Order returned<\/td><\/tr>
RatingProvided<\/code><\/td>Customer gave a score (for example, a post-purchase NPS<\/a>)<\/td><\/tr>
ReviewProvided<\/code><\/td>Customer left a review<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Meta adds a caveat: these events should represent interactions that happen in the messaging thread<\/strong>. If the purchase happens on your website or app, use the Conversions API for web or app events, with the matching action source.<\/p>\n\n\n\n
Node.js example<\/h2>\n\n\n\n
The example below sends Purchase<\/code> when the order is paid, using the ctwa_clid<\/code> stored with the conversation. It flags the order as sent to avoid repeating the event, because Meta doesn’t deduplicate events for this API: the official recommendation is for advertisers to deduplicate before sending.<\/p>\n\n\n\n
const GRAPH = 'https:\/\/graph.facebook.com\/v26.0';\nconst { META_CAPI_TOKEN, DATASET_ID, WABA_ID } = process.env;\n\nexport async function sendPurchase(order, db) {\n  if (!order.ctwa_clid || order.capi_sent_at) return; \/\/ no click or already sent\n\n  const body = {\n    data: [{\n      event_name: 'Purchase',\n      event_time: Math.floor(new Date(order.paid_at).getTime() \/ 1000),\n      action_source: 'business_messaging',\n      messaging_channel: 'whatsapp',\n      user_data: { whatsapp_business_account_id: WABA_ID, ctwa_clid: order.ctwa_clid },\n      custom_data: { currency: 'BRL', value: order.total },\n    }],\n  };\n\n  const r = await fetch(`${GRAPH}\/${DATASET_ID}\/events?access_token=${META_CAPI_TOKEN}`, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application\/json' },\n    body: JSON.stringify(body),\n  });\n\n  const result = await r.json();\n  if (!r.ok) throw new Error(`CAPI: ${result.error?.message ?? r.status}`);\n\n  await db.markCapiSent(order.id, new Date());\n  return result;\n}<\/code><\/pre>\n\n\n\n
If you prefer no-code tools, the same POST<\/code> can go out from an HTTP node in n8n<\/a>.<\/p>\n\n\n\n
Without a ctwa_clid: hashed customer data<\/h2>\n\n\n\n
Not every conversion has a ctwa_clid<\/code>, for example a conversation that started before you began storing the click. In that case, the official guide lets you send SHA-256 hashed customer data instead of the click, and Meta tries to match the event to an ad. Rules for this path:<\/p>\n\n\n\n