
Table of Contents
ToggleMeta Conversions API for Business Messaging lets you tell Meta what happened after someone started a chat from one of your ads. The ad platform can see the click and the first message, but the sale, the qualified lead or the order often happens later, inside the chat or in a CRM. This guide explains how Meta Conversions API for Business Messaging works from start to finish, using Meta’s own documentation, and it lists the common problems with what to check for each, so you can find a fix quickly.
This guide is based on Meta’s official documentation, checked in November 2026. Advice is marked as advice, and a point that Meta’s pages do not state is marked as such. Meta’s pages also contradict each other in a couple of places, and I note those instead of picking a number for you.
Meta’s onboarding guide for the Conversions API for Business Messaging covers three kinds of ads: ads that click to Messenger, to WhatsApp and to Instagram Direct. For each one, your server sends Meta an event, such as a purchase or a qualified lead, tied to the person who clicked the ad. This guide follows WhatsApp most closely and covers Messenger and Instagram wherever they differ.
Meta says events should only describe interactions inside the messaging thread. If a conversion happens somewhere else, such as on your website or in your app, Meta’s FAQ says to send it through the matching Conversions API product: web for website conversions and app events for app conversions. Attribution for those still uses the web click ID. So Meta Conversions API for Business Messaging is not a replacement for your website setup. It is the part of your tracking that covers conversations.
Advice: you need Meta Conversions API for Business Messaging when the sale or the qualified lead is confirmed in the chat, or later in a CRM after a conversation that began in a chat. A browser pixel cannot see those moments, because nothing loads in a browser when a salesperson marks a deal as won. Sending the event from your server is how Meta hears about it.
There is also an optimization angle. Meta’s FAQ says purchase optimization is available for ads that click to Messenger and WhatsApp, but not for Instagram, where campaigns can be optimized for conversations instead. That is a reason to get the Purchase event right even if your reporting needs are modest.
Tap each step to see what happens there, and where real setups usually break.
Meta attaches a click ID called ctwa_clid to this tap. It is the only thread that ties the coming chat back to the exact ad and campaign.
If it breaks here
ctwa_clid is ever created. See the debug guides.The click ID travels invisibly with the messages the customer sends from that ad tap. It never appears in the chat window, so you cannot see it by looking at the conversation.
If it breaks here
ctwa_clid through.The webhook payload carries a referral block that contains ctwa_clid. Your system must read it and store it with the conversation, because later messages do not repeat it.
If it breaks here
referral block, or saves it against the wrong conversation. The thread to the ad is lost for good. Find the fix on the Debug page.Your server sends a Conversions API event with action_source set to business_messaging, messaging_channel set to whatsapp, your WhatsApp Business Account ID, and the saved ctwa_clid.
If it breaks here
Meta uses ctwa_clid to credit the conversion to the right campaign. The results show up in Events Manager and in your ads reporting as messaging conversions.
If it breaks here
test_event_code left in live traffic, or an event_time older than 7 days. More guides on the Debug page.The requirements for Meta Conversions API for Business Messaging differ a little by channel. Start with WhatsApp, then check the Messenger and Instagram notes if you run those ads too.
For ads that click to WhatsApp, Meta’s guide lists these requirements and steps:
whatsapp_business_management and whatsapp_business_manage_events.waba_id) from the completed Embedded Signup flow./{WHATSAPP_BUSINESS_ACCOUNT_ID}/dataset creates one, or returns the existing one, and a GET to the same endpoint retrieves the dataset_id.ctwa_clid, taken from the referral object in the Messages webhook. Store it with the conversation, then send it when the conversion happens.For ads that click to Messenger, Meta’s guide asks for a developer app integrated with the Messenger API and advanced access to the page_events permission. The token needs that permission, and you can reuse the one from Facebook Login for Business. You also need the page_id of the Page you report for. The dataset comes from a POST to /{PAGE_ID}/dataset, and the Page-scoped ID (PSID) comes from the Messages webhook.
For ads that click to Instagram Direct, the guide asks for the same kind of app and advanced access to instagram_manage_events. The token can come from Facebook Login for Business or from the Instagram API with Unified Login. You need the instagram_user_id, the dataset comes from a POST to /{IG_USER_ID}/dataset, and the Instagram-scoped ID comes from the Messages webhook.
Meta’s page carries a notice saying Ads Management Standard Access is now Marketing API Access Tier, with the Full Access threshold at 500 Marketing API calls in the past 15 days. Several sections of the same page still cite 1,500 calls. The notice looks like the newer figure, but Meta’s page does not say so outright, so read the current number on Meta’s page before you plan around it.
Mixing up IDs is easy, because several are long numbers that look alike. For WhatsApp:
/{DATASET_ID}/events.user_data.whatsapp_business_account_id.access_token parameter.referral object in the Messages webhook and goes in user_data.ctwa_clid.user_data.page_id, which is required on the WhatsApp path without a ctwa_clid (covered in Step 3).Meta’s FAQ adds two rules about datasets. Only one dataset can be linked to a Page, and existing datasets can be reused. Advice: keep the dataset ID and the account ID in clearly named variables in your code, because the request lands in the wrong place if you swap them.
Every event you send through Meta Conversions API for Business Messaging uses the same top level fields in the data array. The values below come from Meta’s guide unless marked otherwise.
| Field | What to send | Note |
|---|---|---|
event_name | One of 14 names | Listed below |
event_time | A Unix timestamp | The onboarding page gives no rules for it |
action_source | business_messaging | Used in all of Meta’s examples |
messaging_channel | whatsapp, messenger or instagram | The channel where the chat happened |
user_data | Depends on the channel | See the sections below |
custom_data | currency and value | The fields in Meta’s examples |
Meta’s FAQ lists the supported names: Purchase, LeadSubmitted, InitiateCheckout, AddToCart, ViewContent, OrderCreated, OrderShipped, OrderDelivered, OrderCanceled, OrderReturned, CartAbandoned, QualifiedLead, RatingProvided and ReviewProvided. Names from your website setup, such as Lead, are not on that list. The list has LeadSubmitted instead.
Meta’s guide does not define each name, so the mapping below is my recommendation, not Meta’s wording:
currency and value filled in.Advice: send only the events you will actually use to judge your ads. A short, reliable list is easier to keep correct than all 14.
Every example in Meta’s guide sets action_source to business_messaging. Meta’s general server event documentation lists other values, such as website, app, phone_call and chat. Advice: for this API, use business_messaging, as in Meta’s examples, and set messaging_channel to the channel where the conversation happened.
The onboarding page gives no rules for event_time. Meta’s general server event documentation says it can be up to 7 days before you send the event, and that one older event makes the whole request fail. That page describes the general Conversions API, so treat it as the best available guide for messaging events, not a statement about them. Advice: send each event soon after the conversion happens, so the timestamp never gets close to that limit.
With a ctwa_clid: send whatsapp_business_account_id and ctwa_clid. Meta says to send the ctwa_clid whenever you have it, because it matches more reliably.
Without a ctwa_clid: Meta describes a separate path for cases such as a conversation that started before you stored click IDs. The event needs page_id, and Meta says an event without it is rejected even with valid customer information. It also needs whatsapp_business_account_id and at least one customer parameter from em, ph, fn, ln, ct, st, zp, country, ge or db, normalized and hashed with SHA-256. An external_id does not work for matching on this path. Meta lists three limits for it: matching is not guaranteed, events are attributed only to ad interactions from the past seven days, and the path is available in a subset of countries.
For Messenger, the sample uses page_id and page_scoped_user_id. For Instagram, it uses instagram_business_account_id and ig_sid. Those fields belong to their own channels. Advice: build each event from the sample for its own channel, so no field from another channel is left over.
Meta’s customer information parameters page says the personal fields are normalized first and then hashed with SHA-256:
em (email): strip leading and trailing spaces, then lowercase.ph (phone): remove symbols, letters and leading zeros, and include the country code.fn and ln (names): lowercase a to z letters without punctuation.ct, st, zp, country, ge and db: each has its own format rule on that page, for example db as YYYYMMDD and country as a lowercase two letter code.The same page says ctwa_clid, page_id and page_scoped_user_id are not hashed. Do not hash the ctwa_clid.
A minimal request for Meta Conversions API for Business Messaging is a POST to the events endpoint of your dataset, and this is Meta’s example for the ctwa_clid path. The IDs and the token below are placeholders in angle brackets, so replace each one with your own value and never publish a real token.
POST https://graph.facebook.com/v26.0/<DATASET_ID>/events?access_token=<ACCESS_TOKEN>
{
"data": [
{
"event_name": "Purchase",
"event_time": 1675999999,
"action_source": "business_messaging",
"messaging_channel": "whatsapp",
"user_data": {
"whatsapp_business_account_id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"ctwa_clid": "<CLICK_TO_WHATSAPP_CLICK_ID>"
},
"custom_data": {
"currency": "USD",
"value": 123
}
}
],
"partner_agent": "<PARTNER_NAME>"
}Replace event_time. The value 1675999999 is the example from Meta’s page and is an old timestamp. Use the time the conversion actually happened, or the request will not fit the 7 day rule described above.
The API version in the URL is the one shown in Meta’s guide when it was checked, so confirm the current version on Meta’s page. The partner_agent field is in Meta’s sample for partner integrations. Meta’s FAQ says to use one app per partner so Meta can identify your events, and to set partner_agent to the name Meta assigned you if you already have several apps.
This is Meta’s second sample, for conversations where you have no click ID. Compare it with the first one: page_id is added, and hashed customer information replaces the click ID.
{
"data": [
{
"event_name": "Purchase",
"event_time": 1675999999,
"action_source": "business_messaging",
"messaging_channel": "whatsapp",
"user_data": {
"page_id": "<PAGE_ID>",
"whatsapp_business_account_id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"em": ["<SHA256_HASHED_EMAIL>"],
"ph": ["<SHA256_HASHED_PHONE>"]
},
"custom_data": {
"currency": "USD",
"value": 123
}
}
],
"partner_agent": "<PARTNER_NAME>"
}Advice: treat this path as a fallback in Meta Conversions API for Business Messaging, not a plan. Meta says matching is not guaranteed on it and that it only attributes ad interactions from the past seven days, so the better fix is to capture the ctwa_clid when the chat starts.
This is an illustration, not a real account. A shopper clicks a Click to WhatsApp ad and sends a first message. Your webhook receives the message, and the referral object carries the ctwa_clid. Your system saves it on the conversation record, next to the contact and the WhatsApp Business Account ID.
Over the next few days, your team qualifies the lead and later closes the sale in the chat. When the CRM stage changes to paid, your server builds one Purchase event. It sets action_source to business_messaging and messaging_channel to whatsapp. It puts the saved ctwa_clid and the account ID in user_data, and adds the amount and currency in custom_data. The event_time is the moment the payment was confirmed.
Before sending, your server checks its own record to see whether that order was already sent. It then posts the event to the dataset endpoint. Afterwards, someone opens the dataset in Events Manager to confirm the event arrived. Every step in that chain depends on the click ID being saved when the chat starts.
Meta’s onboarding guide does not show a sample success response. It says that after a successful send the event should appear in Events Manager for the dataset, and it states no processing delay. Meta’s general Conversions API guide says to verify events within 20 minutes, and that the Overview shows raw, matched and attributed event counts. That page describes the general API, so treat the 20 minutes as a guide, not a promise for messaging events.
Advice: read “received” as “Meta accepted the request”, not as “the conversion was matched and attributed”. Meta’s pages do not say that a successful send guarantees a match, and for the path without a ctwa_clid Meta states that matching is not guaranteed.
Meta’s Conversions API support page says an invalid payload returns a 4xx response with minimal error details in the response body. It does not define specific error subcodes. That is why the table in Step 6 says so wherever Meta gives no definition for a code.
Meta’s guide says Meta does not handle deduplication for Meta Conversions API for Business Messaging, so you must deduplicate before sending. The onboarding page does not mention event_id. Advice: keep a record of every CRM event you have already sent, keyed by something stable such as the order or deal ID, and check it before every send. Then a retry after a timeout can never create a second conversion.
Meta’s general guide says events sent with test_event_code are not dropped. They flow into Events Manager and are used for targeting and ads measurement, so the field is for testing only and has to come out of your production payload.
Advice: keep the access token for Meta Conversions API for Business Messaging in a server side environment variable, never in front end code, screenshots or support tickets. The URL in Meta’s example carries the token as a query parameter, so avoid logging full request URLs.
This table lists common problems with chat events, the likely cause and what to check. Where Meta does not document a cause, the table says so instead of guessing. Step by step fix guides for several of these problems are collected on the debug hub.
| Problem | Likely cause | What to check |
|---|---|---|
| The API returns error 2804066 | Meta rejected the event name in a chat event. Meta’s list for chat events has 14 names, and a website name such as Lead is not on it. Meta’s documentation does not define this subcode, so this reading comes from developer reports | Check that event_name is one of the 14 names, for example LeadSubmitted instead of Lead. |
| The ctwa_clid is missing when the conversion happens | The ctwa_clid arrives in the referral object of the Messages webhook, so it is missing when that webhook or the referral data never reaches your system | Check that your system receives the Messages webhook, and that it saves the ctwa_clid from the referral object when the chat starts. |
| Email is sent without hashing | The hashing step is missing, or it runs for only some event types. Meta requires customer parameters to be normalized and hashed with SHA-256 | Normalize the email (trim and lowercase), then hash it with SHA-256 before every send. |
| action_source is missing | Meta’s examples set action_source on every event, and business_messaging for messaging events | Check that every event object carries action_source set to business_messaging. |
| The API returns error 2804131 | Meta cannot find a Page tied to the dataset, according to developer reports. Meta does not define this subcode | Check that the dataset ID in the URL belongs to your WhatsApp Business Account, and build the event from Meta’s sample for your channel and path. |
| The API returns error 2804081 | Meta’s public documentation does not define this subcode, so the cause depends on your payload | Compare your payload with Meta’s sample for your channel, field by field, and test it in the CAPI Debugger. |
| action_source is rejected as invalid | Meta’s examples use business_messaging for all messaging events | Check the exact spelling and value: business_messaging, in lowercase, with an underscore. |
| Events are received but not showing | Advice, not from Meta’s pages: the event may have gone to a different dataset than the one you are viewing, or it may have been rejected | Open the dataset whose ID is in your request URL, and check the response for a 4xx error. |
| The ctwa_clid was hashed | Meta lists ctwa_clid among the values that are not hashed | Send the ctwa_clid exactly as received, and hash only personal fields such as email and phone. |
| Duplicate conversions appear | Meta does not deduplicate events for Meta Conversions API for Business Messaging, so you must do it before sending | Keep your own record of sent events, keyed by order or deal ID, and check it before every send. |
| event_time looks wrong, for example in milliseconds | Meta’s example uses a 10 digit Unix timestamp in seconds, and the onboarding page states no other rule | Send a timestamp in seconds that matches the real conversion time, and send it soon after the conversion. |
Before you send live events through Meta Conversions API for Business Messaging, run one payload through the free CAPI Debugger. It checks business messaging events only, meaning events with action_source set to business_messaging, and it does not cover website pixel events. Its page says it checks a payload entirely in your browser and that nothing is uploaded. A report is saved on the site only if you create a share link or request a fix, and access tokens are never stored. Advice: replace the real token with a placeholder before you paste anyway.
ctwa_clid is saved when the chat starts and sent unchanged and unhashed.event_time is the real conversion time, sent soon after it happens.test_event_code is removed from the production payload.That is the full flow of Meta Conversions API for Business Messaging, from permissions to a checked event. When something breaks, run the payload through the free CAPI Debugger above, then check the table in Step 6 or open the debug hub.
It is the way to send conversions that happen in a Messenger, WhatsApp or Instagram Direct conversation back to Meta for ads that click to those apps. The events describe interactions inside the messaging thread, such as a purchase or a qualified lead.
Meta lists 14: Purchase, LeadSubmitted, InitiateCheckout, AddToCart, ViewContent, OrderCreated, OrderShipped, OrderDelivered, OrderCanceled, OrderReturned, CartAbandoned, QualifiedLead, RatingProvided and ReviewProvided. Meta says events should only cover interactions within the messaging thread.
Meta says to send it whenever you have it, because it matches more reliably. Without it you must use the separate path with page_id, the account ID and at least one hashed customer parameter, and Meta states that matching is not guaranteed on that path.
No. Meta’s FAQ says Meta Conversions API for Business Messaging does not handle deduplication, so you must deduplicate before sending. Keep your own record of what you have sent.
Send those through the matching Conversions API product, web for website conversions and app events for app conversions. Meta says attribution still uses the web click ID.
Yes, Meta says existing datasets can be linked. Only one dataset can be linked to a page.
Yes, Meta’s guide has a section for ads that click to Instagram Direct, with its own permission, account ID and sample request. Meta also says purchase optimization is not available for Instagram ads, although Instagram campaigns can be optimized for conversations.