Setting up conversion measurement | Developer Documentation
Setting up conversion measurement
Updated: Mar 27, 2026
Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.
Using Marketing Messages API for WhatsApp, you can integrate your marketing messages with events, allowing you to measure the rate and cost at which a Marketing message sent via Marketing Messages API for WhatsApp leads to a downfunnel event like “purchase” on your website or app.
Conversion measurement is built on the same events that you can send to Meta when using Ads, making it seamless for businesses who are already integrated with Events for Ads purposes (for example, via Pixel or Conversions API for websites, or Meta SDK in their mobile app), to leverage the same reporting automatically with no setup.
If a business is using both marketing messages on Marketing Messages API for WhatsApp and Ad Campaigns on the same business portfolio, conversion events reported will be automatically attributed to the last Meta touch (either Marketing Messages API for WhatsApp click or Ad click) before the event, based on the attribution window settings of each. For example, if a business is running both an Instagram Ad campaign and a Marketing message campaign on MM API for WhatsApp, each with a URL pointing to the same website for a sale, a user who purchases after clicking on both the Instagram Ad and the Marketing message will be attributed to either the MM API for WhatsApp click or the Ad click, based on the attribution window settings of each. This helps businesses better understand the holistic picture of their Ad and Marketing message campaigns in driving outcomes.
Understanding linked Ad entities
When a business registers for Marketing Messages API for WhatsApp, read-only Ad accounts are created under their business portfolio, which are synced to each WhatsApp Business Account under the same portfolio. Note that marketing messages are separate and distinct from Ads - the use of “Ads” terminology below represents the use of Ads entities as technical constructs only.
No action is needed on the part of the business or partner - these linked read-only Ad accounts are kept in sync with any changes made to Marketing templates, so that any new or updated marketing templates are reflected by their linked ad entity.
Linking Marketing templates to Ad accounts provides several benefits:
Common UI and API for marketing teams: Businesses can view their Marketing Messages API for WhatsApp marketing campaigns and campaign metrics as “Campaigns” in Ads Manager’s “Marketing Messages” tab, and via API using the Marketing API “Insights API”. Using these interfaces helps a business’ marketing teams view their Ads and Marketing message campaigns using common interfaces and terminology, instead of viewing Ad campaigns in one place and marketing campaigns sent via WhatsApp in another.
Template-to-Ad-sync guidelines
Understanding automatic objective setting
In order to measure Conversion events, Marketing Messages API for WhatsApp automatically syncs Marketing templates to corresponding Ads entities (Campaigns, Message sets, and Ads) with configurations that allow for Conversion reporting of an assumed objective.
This linking process happens automatically, to reduce the integration complexity of Marketing Messages API for WhatsApp for businesses. For those familiar with Meta’s Ads ecosystem, note that these Campaign and Ad Set parameters will not change how messages are delivered via Marketing Messages API for WhatsApp - they are only set so that reported events can be correctly attributed.
The following table shows how Marketing templates are mapped to Ads entities.
| Campaign parameters | Message Set parameters | |
|---|---|---|
Marketing templates with no CTA URL button | Objective:OUTCOME_SALES | OptimizationGoal: Impression |
Marketing templates with a CTA URL button that points to a website or app without event reporting enabled. | Objective:LINK_CLICKS | OptimizationGoal: LinkClicks |
Marketing templates with a CTA URL button that points to a website or app with event reporting enabled. | Objective:LINK_CLICKS | OptimizationGoal: OffsiteConversion |
While most changes to Templates will be automatically synced with Ads (for example, text content), Campaign and Message set parameters are synced only once when a business first onboards to Marketing Messages API for WhatsApp or creates a new Template, in order to maintain a consistent campaign and message set structure when reporting on clicks and conversions from messages sent using that Template. This means that if you wish to add, edit, or remove a URL from a CTA button on a Template, you must create a new Template in order to correctly capture click and conversion metrics for the updated URL.
URL requirements for conversion measurement
Meta appends a click ID to the URLs you send in CTA buttons on marketing template messages. The purpose of the click ID is to attribute events you report via Meta Pixel, Conversions API (web or app events), or the Meta SDK.
The click ID is Meta-generated and is commonly attached as the
fbclid query parameter.Example URL with
fbclid query parameter:https://www.jaspersmarket.com/?fbclid=IwAR2F4-dbP0l7Mn1IawQQGCINEz7PYXQvwjNwB_qa2ofrHyiLjcbCRxTDMgk
URL compatibility (short links, redirects, and URL rewriting)
Some short-link and redirect services can interfere with conversion measurement if they strip, overwrite, or fail to forward query parameters that Meta appends. If you use a short-link provider or URL rewriting service, ensure it preserves all query parameters end-to-end.
Example where fbclid is dropped:
https://www.jaspersmarket.com/checkout?campaign=whatsapp_templateYour link partner rewrites it to a short link that redirects to your site: https://www.example.com/jaspersmarketBefore sending, Meta appends a click ID to the short link: https://www.example.com/jaspersmarket?fbclid=xyz789When the user clicks, the short-link service redirects to your site but drops the query string, sending the user to: https://www.jaspersmarket.com/checkout?campaign=whatsapp_template (missing fbclid=xyz789)The click ID is not preserved through the redirect, which can reduce Meta’s ability to attribute conversions to the originating click.
URL parameter ordering issues
Appending additional query parameters after the
fbclid parameter can cause redirection issues on some platforms. If your system adds custom parameters to a URL, ensure that the fbclid parameter is not disrupted or truncated by subsequent parameters. Test the full URL (with all parameters) to confirm that the destination resolves correctly and that fbclid is accessible to your site or app.Recommendations
If you use short links or redirects:
fbclid).Validate conversion reporting in Ads Manager and Insights API before sending production workloads.Avoid appending parameters after fbclid in ways that could disrupt the URL structure.If you experience issues, work with your partner to ensure query parameters are preserved, or reach out to Meta with details.
Android deep links for conversion measurement
Android routes deep links using intent filters declared by apps. A deep link URL has three parts:
https, myapp) — helps determine which app can open the linkPath (for example, /product/123) — the route inside the appQuery parameters (for example, ?fbclid=...) — includes attribution data like fbclid, campaignId, al_applink_data, and othersWhen a user taps a deep link, Android:
onCreate() and/or onNewIntent()), where the app must read the full URL (including query parameters).Android passes the URL, but your app must explicitly capture and persist attribution parameters. If you don’t, they can be effectively “lost” after the first screen.
Attribution parameters like
fbclid can be stripped, cached incorrectly, or not passed through as expected due to one or more of:onCreate() but not onNewIntent()Not persisting the parameters for later use (install/deferred deep linking/session attribution)Redirecting internally and dropping query params when rebuilding a new URIImplementation checklist
To ensure the click ID works correctly, the receiving Android app should:
onCreate()) and warm start/re-use (onNewIntent())Extract attribution params (at minimum fbclid, and any others you rely on)Persist them for later conversion reporting/session attribution
SharedPreferences or a database) with a timestampRefresh if a newer value arrives (these identifiers can change over sessions)Do not drop query parameters when redirecting internally
Test deep link parameter preservation on Android
When you open a deep link that includes
fbclid, your app should be able to log (or otherwise confirm) that it received the URI including fbclid, and that it persisted it for subsequent events.Use a test link like:
myapp://some/path?fbclid=TEST123&campaignId=TESTCAMPAIGN
Or an
https:// app link equivalent if you support it.Test using adb
You can simulate what Android does by sending an Intent yourself:
adb shell am start -W -a android.intent.action.VIEW \
-d "myapp://some/path?fbclid=TEST123&campaignId=TESTCAMPAIGN"
Then confirm your app receives
fbclid and persists it.Measure website conversions with Meta Pixel or Conversions API
Businesses who are reporting events from their website using Meta Pixel or Conversions API for web, can measure when clicking on a URL in a marketing message sent via Marketing Messages API for WhatsApp leads to one of 3 conversion events.
If a business is not yet reporting Offsite Conversion events from their website, see the following documentation to set up event reporting:
Once a business is reporting events via Pixel or Conversions API, the following 3 standard events are automatically associated with website visitors who arrived at the site via a CTA URL from a marketing message sent via MM API for WhatsApp:
When a user clicks a CTA URL in a Marketing Messages API for WhatsApp message and performs any of the above 3 events, Meta will automatically attribute the conversion event to the MM API for WhatsApp Campaign, and make those analytics available to you or your Partner via the Insights API, which your Partner may surface on their own reporting surfaces that you are accustomed to using.
Note that if this conversion event is also being used to measure the efficacy of Ads on Facebook or Instagram, Meta will attribute the conversion to the ‘last touch’ interaction of the user. For example, if a user arrives at your website via an ad on Facebook, and then closes their browser window and later that day returns to your website via clicking a link from a MM API for WhatsApp message and purchases an item, that purchase conversion event will be attributed to the MM API for WhatsApp campaign (and not the ad on Facebook) as the most recent interaction.
Measure app conversions with Meta SDK or Conversions API
Businesses can use Marketing Messages API for WhatsApp to measure when marketing messages lead users to perform app events, such as purchases and app activations. See Conversions API for App Events for an introduction to app events.
The following app conversion events are available for MM API for WhatsApp:
Businesses can capture App conversion events in 3 ways. See Conversions API for App Events for more information.
Using the Meta SDK
campaign_ids from al_applink_data parameters from the deep link that the user clicked from.Example deep link:
exampleapp://applink/ad_landing_recommend?data={"goods_id":"39109246","page_type":"B"}&al_applink_data={"target_url":"https://www.exampleapp.com&fbclid=IwZXh0bgNhZW0BMAABHbKVD62Fa0uTdpAh6KZn16BmrnWgsTbZgiCEsKGLOcF9RDncEAsbJKWp0Q_aem_y0zBYthdxb0j9epvkZum7w","extras":{"fb_app_id":312563225523989},"referer_app_link":{"url":"fb:///?app_id=312563225523989","app_name":"Facebook"},"campaign_ids":"IwAR2rBBgtFjvI_IUUes4nZ6FcQ0dtqujIz1w9JIwrs1YKKn7tGIIqC4kKrXk_wapm_fVVosPGBQJWpvSW8Z8emXg_aem_pyDxR3ch5qDkVdd0Y138yg","ad_id":"1234567","adgroup_id":"1234567","campaign_id":"1234567","campaign_group_id":"1234567","account_id":"1234567"}
Via a 3rd party mobile measurement partner
Some mobile measurement platforms will automatically forward App conversion events to Meta on your behalf. No integration effort is needed on your part. See Partner showcase
No comments to display
No comments to display