Marketing Messages
- Marketing Messages API for WhatsApp | Developer Documentation
- Get started | Developer Documentation
- Features | Developer Documentation
- Onboard | Developer Documentation
- Setting up conversion measurement | Developer Documentation
- Tracking click events | Developer Documentation
- Viewing metrics | Developer Documentation
- Deep links | Developer Documentation
- Send Marketing Messages | Developer Documentation
- Onboard business customers | Developer Documentation
- Set a max-price for marketing messages (BETA) | Developer Documentation
Marketing Messages API for WhatsApp | Developer Documentation
Marketing Messages API for WhatsApp
Updated: Feb 10, 2026
Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.
MM API for WhatsApp is our next-generation marketing solution built to enhance the customer experience and deliver the right message to more of the right people.
Key benefits
Send all your marketing traffic to the
/marketing_messages endpoint for automatic routing of eligible business’ messages.Footnotes
Get started | Developer Documentation
Get started
Updated: Feb 10, 2026
Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.
Learn how to send a template message with the Marketing Messages API for WhatsApp (MM API for WhatsApp).
Requirements
Step 1: Accept Terms of Service
Step 3: Verify message was sent through the status webhook
Geographic availability of features
Some advanced features and reporting capabilities of MM API for WhatsApp are available only in particular geographies due to Meta policy and/or local regulation.
European Economic Area, United Kingdom, Japan, South Korea
United States
Cuba, Iran, North Korea, Syria, and three sanctioned regions in the Ukraine (Crimea, Donetsk, Luhansk):
Russia
Starting June 20, 2025, businesses in Russia will be able to use MM API for WhatsApp with the following feature exceptions:
Messages sent by a business with a Meta business profile in Russia, or using a payment method with a Russian address, will not receive delivery optimizations.Messages sent from a business phone number in these countries, or to a consumer in these countries, will not have click and conversion reporting metrics available. For businesses in these countries, metrics are not available on Ads Manager UI or Insights API. As with Cloud API, metrics will continue to be available via Business Management API and WhatsApp Manager UI conversation metrics.All other features of MM API for WhatsApp continue to be available.
Learn more
Features | Developer Documentation
Features
Updated: Feb 10, 2026
Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.
Marketing Messages API for WhatsApp offers added features that are not available on Cloud API, such as performance benchmarks and recommendations, time-to-live, and automated creative optimizations (in testing).
For more detail, see the comparison tables below.
Optimization features
| Description | Marketing Messages API for WhatsApp (Supports Marketing) | Cloud API (Supports Auth, Utility, Service, Marketing) |
|---|---|---|
Quality-based delivery: Improving deliveries of high engagement messages. | Yes: Marketing Messages API for WhatsApp factors if a message is high engagement into delivery decisions, offering up to 9% higher deliveries vs. Cloud API (see footnote below). High engagement marketing messages refers to messages that are expected by users, relevant, and timely, and therefore more likely to be read and clicked. | No: Message quality does not factor into per-user marketing message limits. No ability to increase delivery for high engagement messages. |
Automated creative optimizations: Automatic enhancements to creative to increase message performance. | Yes (pilot): Automatically enhance the visual appeal and engagement of marketing template messages. See full list of capabilities here. | No |
Marketing message formats
| Description | Marketing Messages API for WhatsApp (Supports Marketing) | Cloud API (Supports Auth, Utility, Service, Marketing) |
|---|---|---|
Animated Image (GIF) Header: Marketing message templates support a GIF media type in the header. | Yes | No |
Android App Deep Links: Links that directly open up the app on a customer’s phone. | Yes | No |
Customizable Message Validity Periods: Set a time-to-live for messages that should expire if they cannot be delivered soon enough. | Yes: TTL can range from 12 hours to 30 days. | Limited: Only supports Authentication and Utility messages. |
Basic marketing message formats: Media, carousel, product catalog, flow, interactive list, interactive reply, etc. | Yes | Yes |
Guidance
| Description | Marketing Messages API for WhatsApp (Supports Marketing) | Cloud API (Supports Auth, Utility, Service, Marketing) |
|---|---|---|
Benchmarks: Comparison of read and click rates versus similar templates from businesses in your region. | Yes | No |
Recommendations: Evidence-based recommendations to improve the performance of your template. | Yes | No |
Metrics
| Description | Marketing Messages API for WhatsApp (Supports Marketing) | Cloud API (Supports Auth, Utility, Service, Marketing) |
|---|---|---|
Conversion metrics: Conversions on Web and App. | Yes: Measure marketing messages leading users to perform app events, such as “Add to Cart”, “Checkout Initiated”, and “Purchase”. | No |
Cost metrics: Spend per Template, Cost per click, Cost per delivery. | Yes | Yes |
Basic metrics: Sent, delivered, read, clicked, errors. | Yes | Yes |
Enterprise, Security 5 & Compliance Features
| Description | Marketing Messages API for WhatsApp (Supports Marketing) | Cloud API (Supports Auth, Utility, Service, Marketing) |
|---|---|---|
Local Storage Support: Phone numbers with Local Storage enabled. | Yes | Yes |
Compliance certification: Compliance resources available on the Business Messaging Compliance Center. | Yes: Certification for LGPD, GDPR, System Audit Report, SOC, ISO27001. | Yes: Certification for LGPD, GDPR, System Audit Report, SOC, ISO27001. |
Automatic throughput upgrades: Automatic upgrades (and webhook notifications) to a phone number’s messaging throughput. | Yes | Yes |
Real-time service status updates: Uptime and availability metrics are live on metastatus.com. | Yes | Yes |
Onboarding
| Description | Marketing Messages API for WhatsApp (Supports Marketing) | Cloud API (Supports Auth, Utility, Service, Marketing) |
|---|---|---|
Streamlined Onboarding: Onboard via Embedded Signup, Intent API, and Intent UI. | Yes | Limited: Embedded signup only. |
Error Codes: Graph API error codes. | Yes | |
Onboarding Status via API: Granular eligibility status data and error codes. | Yes: A new eligibility status field has been introduced to better report on the API onboarding status. | Limited |
Coexistence: Onboarding WhatsApp business app users. | Yes | Yes |
Footnote
The A/B test was conducted with ~12 million delivered marketing messages sent by advertisers in India between 1st Jan 2025 to 31st Jan 2025. It compared Marketing Messages API for WhatsApp optimized delivery to standard Cloud API delivery for high engagement messages only (that is to say, more reads, clicks, etc.) and the analysis consisted of a t-test at 95% confidence.
Onboard | Developer Documentation
Onboard
Updated: Feb 10, 2026
Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.
Onboarding to the Marketing Messages API for WhatsApp (MM API for WhatsApp) is a low-effort upgrade to sending marketing messages with optimizations on Cloud API. See the directions below to onboard your business, whether you integrate with the API directly or work with a partner.
When a business registers for the MM API for WhatsApp, read-only Ad accounts are created that are linked to each of the marketing templates that exist under their business portfolio.
These linked accounts allow a business to:
fetch their MM API for WhatsApp insights from the Marketing API “Insights API” to view the same
These read-only ad accounts are kept in sync with any changes to marketing templates, so that any changes to marketing templates are reflected in the linked ad entity.
Follow the steps below to Onboard to MM API for WhatsApp.
Eligibility requirements
In order to use the Marketing Messages API for WhatsApp (MM API for WhatsApp), a business must comply with applicable legal, vertical and content restrictions (country dependent) outlined in WhatsApp Business Messaging Policies.
In addition, the following requirements must be met:
WABA is active and not restricted from messaging due to any violationsWABA tax country is not in sanctioned regionsOwner Business country is not in sanctioned regions
MM API for WhatsApp will continuously update vertical eligibility and policies to comply with various policies and regulations internationally, so these requirements may change.
Checking eligibility status (alternative)
This field will be deprecated in version 24.0. We recommend using the
marketing_messages_onboarding_status field instead.For partner-managed WABAs, businesses can find eligible WABAs using the following endpoint:
Register a phone number on Cloud API
In order to send a message via MM API for WhatsApp, a business phone number must also be registered on Cloud API. MM API for WhatsApp and Cloud API are used together on the same phone number:
Cloud API allows a business to send Authentication, Service, Utility, and non-Optimized Marketing template messages and freeform messages, and receive inbound messages from consumers on a business phone number.
MM API for WhatsApp allows a business to send marketing messages with optimizations, over the same phone number as is registered on Cloud API.
WhatsApp Business phone numbers that are not registered on Cloud API cannot be used with MM API for WhatsApp.
If a business phone number is already registered on Cloud API, phone number verification is not required when registering for MM API for WhatsApp, as no new phone numbers are registered during the MM API for WhatsApp registration process. Existing Phone Numbers remain registered on Cloud API, and will now be eligible to use MM API for WhatsApp in addition to and simultaneously with Cloud API for sending marketing messages.
For solution providers
If you are a solution provider onboarding your end businesses, refer to onboard business customers.
Onboarding business customers
You can instruct your business customers to have someone with full control to the business portfolio to accept the Terms of Service and onboard MM API for WhatsApp via WhatsApp Manager.
Open WhatsApp Manager > Overview.In the Alerts section, click Accept terms to get started for Marketing Messages API for WhatsApp.Follow the steps to finish signing MM API for WhatsApp Terms of Service.
Your business customers should be able to start sending messages via MM API for WhatsApp.
If you are unable to access your WhatsApp Manager, find your business portfolio admin here.
For business customers without a partner
If your business directly integrates with Cloud API without a partner, follow the instructions below to accept the Terms of Service and onboard to MM API for WhatsApp.
Navigate to the App Dashboard > WhatsApp > Quickstart panel.On the Quickstart page, locate the “Improve ROI with Marketing Messages API for WhatsApp” card and click the “Get started” button.Click on “Continue to integration guide” to accept the Terms of Service
Receive MM API for WhatsApp Terms of Service signed webhook (Preferred)
Note: The ToS event value will be available from September 8th, 2025. Refer to the legacy webhook below.
When the MM API for WhatsApp Terms of Service (ToS) is signed for a business, a new
account_update webhook will be sent for each WhatsApp Business Account (WABA) under your business portfolio. The webhook indicates that the WABA’s business has successfully accepted the MM API for WhatsApp ToS. When the webhook is triggered, your WABA will be allowed to send messages through MM API for WhatsApp.You can use the included business portfolio ID and WABA ID to verify compliance and begin sending messages, or trigger subsequent onboarding actions as needed. This webhook is the preferred webhook to track MM API for WhatsApp onboarding and eligibility status.
Receive onboarding completion webhook (Legacy)
Once you have completed onboarding and linked Ad accounts have been set up, an
account_update webhook will be sent for each WABA under your business portfolio to indicate that onboarding has successfully completed. This webhook contains the ID of the read-only Ad account that each WABA is linked to, for use when calling Insights APIs.Note: This webhook is considered legacy for MM API for WhatsApp onboarding. Please use the MM API for WhatsApp Terms of Service signed webhook.
Important: The
ad_account_linked webhook event will no longer be fired since partners will not receive access to ad accounts.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 others
When 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 URI
Implementation 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.
Tracking click events | Developer Documentation
Tracking click events
Updated: Feb 10, 2026
Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.
Available using Marketing Messages API for WhatsApp (MM API for WhatsApp) and Ads Manager only
Limitations
Viewing metrics | Developer Documentation
Viewing metrics
Updated: Feb 10, 2026
Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.
Conversion metrics will be solely available in the WhatsApp Manager UI and WhatsApp Business Management API that businesses use with Cloud API in October 2025.
As a result, the following conversion metrics will be depreciated:
Businesses that use Marketing Messages API for WhatsApp can view metrics from 4 surfaces:
| ROI Reporting | WhatsApp Business Management surfaces | Ads surfaces |
|---|---|---|
|
Messages sent, delivered, read |
Y |
Y |
|
Total amount spent |
Y |
Y |
|
Cost per delivery |
Y |
Y |
|
CTA URL link clicks |
Y |
Y |
|
Cost per click |
Y |
Y |
|
CTA URL link click rate |
N |
Y |
|
Add to cart (Web + App) |
Y |
Y * |
|
Checkout initiated (Web + App) |
Y |
Y * |
|
Purchase, purchase value (Web + App) |
Y |
Y * |
|
App Activations |
Y |
Y * |
|
Quick Replies |
Y |
Y |
* Requires a business to report this conversion event via Meta Pixel or Conversions API for App Events see Get started with the Meta Pixel and Conversions API.View metrics via UIs
After sending Marketing Messages via Marketing Messages API for WhatsApp, view read-only metrics on sends, clicks, and conversions from two UIs:
Marketing Messages API for WhatsApp metrics, can be viewed in WhatsApp Manager on both Phone Number and Template screens:
Benchmarks and recommendations metrics
Benchmark metrics provide insights into how your business is performing compared to similar businesses in your industry. These metrics are based on data from the past 30 days and take into account various factors that define similar businesses. Based on the benchmark metrics, we provide personalized recommendations to help you improve your template’s performance. If your template’s read rate or click rate falls below the benchmark, we provide suggestions to boost engagement.
Calculating benchmarks
To calculate benchmark metrics, we consider the following characteristics:
We then calculate two key benchmark metrics:
Understanding your ranking and how to use benchmark metrics
When you view your benchmark metrics, you will see a ranking that indicates how your template performs compared to templates in the same category. This ranking is calculated by comparing your template’s performance with the read rate or click rate performance of peer templates with high engagement over the past 30 days.
Use the benchmark metrics to compare your template’s performance to templates from similar businesses over the past 30 days. Benchmarks are calculated daily, with a delay of up to 2 days. This ensures that you have access to updated and relevant data to inform your business decisions.
To access the benchmark and recommendations metrics:
Error metrics
You can see a summary of error messages your template encountered within a given period of time by navigating to the WhatsApp Manager > Message templates > Manage templates panel and clicking on the template. Errors are displayed in the Error messages section.
The period of time can be defined using the date selector dropdown at the top of the page. See Cloud API error codes for a list of error codes and their descriptions.
The most frequently encountered message delivery errors are displayed in the Summary tab:
This information is also displayed as trend lines in the Trend tab:
Deep links | Developer Documentation
Deep links
Updated: Feb 10, 2026
Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.
You can map an Android deep link? to a marketing template URL button that, when tapped, loads a particular location or content within your app.
If you have not onboarded to the Marketing Messages API for WhatsApp (MM API for WhatsApp), your marketing templates will not display any conversion metrics. Learn more about how to measure conversion.
Template creation via WhatsApp Manager
To create a template with a button mapped to an Android deep link:
Note that you can also use the Manage templates panel to edit an existing template and add a deep link-mapped button, but the template will have to undergo template review again.
Form fields
| Field label | Description | Example value |
|---|---|---|
|
Android deep link |
Required. Android deep link URI. |
luckyshrub://deals/summer_solstice |
|
Android fallback URL |
Optional. Fallback URL. If the WhatsApp client cannot load the deep link URI, the client will load this URL in the device's default web browser.
If omitted, the client will attempt to load the URL specified in the Website URL field instead. |
https://www.luckyshrub.com/deals/summer_solstice |
|
Button Text |
Required. Button label text. Maximum 25 characters. |
View deal |
|
Meta app ID |
Required. This is a list of the Meta app(s) associated with your business portfolio. Select the app whose access token you will use to send the template. |
Lucky Shrub (634974688087057) |
|
Type of Action |
Required.
Must be set to Visit website. |
Visit website |
|
URL Type |
Required. Set to Static if your Android deep link or Android fallback URL has no dynamic values, otherwise set to Dynamic. |
Static |
|
Website URL |
Required.
URL of a website to load if the WhatsApp user views the message on a non-Android device, or if the WhatsApp client cannot load your Android deep link URI and no Android fallback URL is specified. |
https://www.luckyshrub.com/ |
Viewing metrics
See our Viewing metrics document.
Send Marketing Messages | Developer Documentation
Send Marketing Messages
Updated: Mar 20, 2026
Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.
Marketing Messages API for WhatsApp allows you to send marketing template messages only. To send other message types or receive messages, use Cloud API in parallel with Marketing Messages API for WhatsApp on the same business phone number.
If you use a partner’s UI portals or APIs to configure and send marketing messages, you can continue to do so, and do not need to use any of the capabilities described in this document - your partner will take care of integrating with MM API for WhatsApp’s message sending functions on your behalf.
Create marketing templates
Marketing templates can be created in several ways:
Via WhatsApp Business Manager UIVia the Business Management API “Message Templates” endpointIf you work with a partner, your partner may offer their own API or user interfaces for template creation, which leverage the “Message Templates” endpoint
See documentation on how to Create and manage templates.
When you create a new marketing template, it takes up to 10 minutes to sync with the corresponding Ad account. This sync allows messages to be optimized and enables measurement of clicks and downstream conversions. Templates inactive for longer than 7 days also require 10 minutes to sync after first use. Wait 10 minutes after creating new marketing templates before sending marketing traffic. The same applies after sending the first marketing message on a dormant template.
Marketing Messages API for WhatsApp supports all marketing templates. In addition, Marketing Messages API for WhatsApp provides the following features that are not available to marketing templates on Cloud API:
Time-To-Live (TTL) for Marketing template messages: If Meta is unable to deliver a message to a WhatsApp user, Meta will retry the delivery for a period of time known as a time-to-live, TTL, or the message validity period. TTL is available for Authentication and Utility template messages on Cloud API, but TTL for Marketing template messages is exclusively available on MM API for WhatsApp. See documentation on how to Create and Manage Templates via API or How to set a custom message validity period via UI for details on how to set TTLs for Marketing template messages.
Other optimizations
Text truncation
Meta truncates text to a specific line-count to increase performance. No text content is changed, the original text is still accessible through the “Read more” button. The exact line count truncation rules are as follows:
Messages without any CTA, but with a link in the message body (overrides the below rules): truncated to 5 linesMessages with a media header (Image, Video, Document, Location, and GIF): truncated to 3 linesMessages without a header (that is, Text messages): truncated to 4 lines
Send marketing template messages
Sending messages follows the same API payload syntax as Sending Messages on Cloud API, and requires the same permissions.
The
/marketing_messages endpoint supports only marketing template messages for MM API for WhatsApp and Cloud API. All other message types (freeform, Authentication, Service, Utility) are not supported, and will produce an error.Marketing messages will only be sent via MM API for WhatsApp when the business customer has met all onboarding requirements. If onboarding requirements are not met, the marketing messages will still be routed via Cloud API. You may disable the ability to route to Cloud API by setting the optional field
product_policy to STRICT.Note: You may still use the
/messages endpoint to send marketing messages through the Cloud API.Request syntax
MM API for WhatsApp provides the following additional features that are not available to Marketing template messages on Cloud API:
Product fallback policy: Set
product_policy to CLOUD_API_FALLBACK to have the API send the outgoing message via Cloud API, if onboarding requirements have not been met. Set to STRICT if you do not want the API to fallback to sending the message via Cloud API.Message activity sharing:
message_activity_sharing is an optional parameter at the message level that enables or disables sharing message activities (for example, message read) for that specific marketing message to Meta to help optimize marketing messages. If this parameter is not provided, the default WABA-level setting will be applied. You can always edit your default setting in Business Settings (see Changelog for a screenshot of this).For details on message types, reference the Cloud API Message Types documentation, as MM API for WhatsApp uses the same message send formatting.
Receiving message status webhooks
MM API for WhatsApp triggers status messages webhooks (sent, delivered, read). In addition, status messages webhooks that describe a message sent via MM API for WhatsApp, and that include pricing information, will have
pricing.category and conversation.type set to marketing_lite. If the message is routed via Cloud API, pricing.category will be set to marketing.Maintain logs of each outgoing message ID, and whether that ID was sent via Cloud API or MM API for WhatsApp, in order to use the unique message ID returned in message status webhooks to identify the origin of the sent message.
Receiving incoming messages
MM API for WhatsApp is a send-only API. It does not receive incoming messages from consumers. To receive incoming messages on a business phone number, use Cloud API in parallel with MM API for WhatsApp on the same phone number.
Onboard business customers | Developer Documentation
Onboard business customers
Updated: Feb 10, 2026
Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.
The MM API for WhatsApp onboarding process is designed to be simple for you as a partner to adopt, making it quick and easy for solution providers (including Solution Partners, Tech Providers, and Tech Partners) to onboard current customers from Cloud API onto the MM API for WhatsApp. If your business directly integrates with Cloud API without a partner, follow the instructions below to accept the Terms of Service and onboard to the MM API for WhatsApp via WhatsApp Manager.
Before you begin
Your app must have advanced access for the following permissions:
whatsapp_business_messaging: This permission allows the app to call the MM API for WhatsApp to send messages.whatsapp_business_management: This permission enables the app to manage WABAs, Phone Numbers, and Templates via WhatsApp Business Management API.ads_read (optional): This permission grants the app access to the Insights API, allowing partners to retrieve metrics on conversions.
If your app does not already have advanced access for these permissions, request advanced access via App Review.
Solution partner integration overview
To assist your customers in using the MM API for WhatsApp, several steps are required:
| Step | Notes |
|---|---|
|
1: Onboard yourself |
Enroll via App Dashboard and follow instructions under the Onboarding yourself. |
|
2: Send messages |
Same Template endpoint and message send payload as Cloud API - only the ‘send message’ endpoint changes. |
|
3: View metrics |
New! Integrate with the Insights API to view the metrics as Cloud API (sent/read/delivered), plus new metrics like Website and App conversions. |
Onboarding yourself
Register yourself for MM API for WhatsApp
To enroll, a solution provider must:
Submit for app review for Advanced App permissions
Solution Providers must use an App with the following Advanced App permissions, when using the MM API for WhatsApp.
If you do not already have an App with the following Advanced App Permissions, it is necessary for your App to go through App review:
| Advanced App Permission | Required in order to do the following on behalf of your customer |
|---|---|
whatsapp_business_messaging |
Call the MM API for WhatsApp ‘send messages’ endpoint, to send messages via Marketing Messages API for WhatsApp |
whatsapp_business_management |
Call WABA, Phone Number, and Template endpoints, for managing WABAs, Phone Numbers, and Templates; and retrieve basic metrics via WhatsApp Business Management API |
ads_read (optional) |
This permission is optional, and is only required to call the Insights API, allowing a partner to fetch advanced metrics on conversions (e.g. Web conversions, App conversions) |
For the app review submission, prepare a screen recording of how each permission is used. It is recommended to show a sample of each action in the “Required in order to do …” column above, to demonstrate each permission in use.
Help the business set up Conversion measurement
See Setting up conversion measurement for details on how businesses can measure when a marketing message from MM API for WhatsApp leads to a conversion (e.g. add to cart, purchase).
Partners are strongly recommended to work with their clients to set up Conversion reporting, so that they can take advantage of measuring the improved metrics and optimizations MM API for WhatsApp provides.
Sending messages
See Sending messages for documentation on how to send messages and receive webhooks on behalf of your customers via MM API for WhatsApp.
Viewing metrics
See the Guide to Viewing metrics for documentation on how to:
Partners are strongly recommended to fetch metrics using the Ads Insights APIs (not Business Management APIs), as these APIs provide richer metrics reporting, including conversion reporting from sources such as Web and App conversion events.
After integrating with reporting APIs (Insights API recommended), surface these metrics in your dashboards and APIs for your customers to use.
Reach out to your Partner Manager for suggestions on metrics best practices, including a copy of Meta’s “Business Messaging Reporting Dashboards Playbook” for partners.
Set a max-price for marketing messages (BETA) | Developer Documentation
Set a max-price for marketing messages (BETA)
Updated: Mar 17, 2026
Marketing Messages API for WhatsApp (formerly known as Marketing Messages Lite API) is now generally available.
Amidst our introduction of the max-price feature on the Marketing Messages API for WhatsApp, there is no change to how we charge on the WhatsApp Business Platform. We continue to charge on a per-message basis, as outlined here.
The max-price feature will become available via Limited Beta as of mid-May and be optional throughout 2026.
What is a max-price?
As announced in March 2026 -- in 2026, we're introducing new pricing features on the Marketing Messages API for WhatsApp to enable businesses to drive higher ROI and have more control to optimize spend for their marketing messaging campaigns.
Our first pricing feature allows businesses to set a maximum price (max-price) per marketing message delivery; when a max-price is set, Meta will charge that max-price or lower for delivery. Businesses can choose to set a max-price the same as, lower than, or higher than the published rate to achieve their objectives per campaign.
Lower costs while maintaining delivery rates similar to current WhatsApp campaigns, by setting max-prices the same as published rates.Target a broader range of customer cohorts on WhatsApp at lower cost, by setting max-prices lower than published rates.Increase delivery rates when customer engagement matters most, like during holidays and peak sales periods, by setting max-prices higher than published rates.
The second pricing feature is the reach estimation tool, which helps businesses set the right max-price by helping them understand estimated delivery rates and costs at different max-prices.
Max-price explainer
The max-price feature allows you to set the maximum price you are willing to pay per message delivery. You are charged your max-price or lower. In the API, you express this as a
Max-price explainer PDF
bid_amount value per 1,000 deliveries within the bid_spec object.Phased roll-out of the max-price feature
We plan to roll out our max-price feature in 3 phases:
Limited Beta starting mid-May 2026 -- Any partner and any directly-integrated business can integrate and use the max-price feature and reach estimation tool. Each partner can enable these features for a limited number of clients.Open Beta starting October 2026 -- Any partner can enable these features for all their clients.General Availability (GA) as of Q2 2027 -- The max-price feature will become required in eligible geographies and fixed, published rates for marketing messages will only apply on the Cloud API.
Before you begin
To use the max-price feature, you must:
Have an active WhatsApp Business Account that has been onboarded to the Marketing Messages API for WhatsApp.Be in a country eligible for MM API for WhatsApp.
Recommendations
Set your max-price at the template level. The
bid_amount in bid_spec is what Meta's delivery system optimizes against. Setting the right max-price when you create the template gives the system the best signal for delivery optimization.The
per_message_bid_multiplier scales the template's bid_amount up or down for individual messages, but the delivery system generally gives better performance optimizing based on the original template-level bid_amount on large amount.For example, if you set a template's
bid_amount to 50,000 and then apply a multiplier of 2.0 on every message, delivery performance might differ from setting the template's bid_amount to 100,000 directly -- even though the effective max-price is the same. Hence we recommend setting up the bid at template level and update the template's bid_spec if needed rather than changing the message level multiplier as a workaround.Ramp up traffic gradually. When sending messages with a new max-price template for the first time, increase volume slowly before sending at scale. This aligns with Template pacing best practices and helps the delivery system optimize effectively.
Create templates with max-price
Request syntax
If
bid_spec is not included, the template uses standard rate card pricing.Request parameters
| Placeholder | Description | Example Value |
|---|---|---|
<ACCESS_TOKEN>String |
Required.
|
|
<API_VERSION>String |
Optional.
Graph API version. |
v25.0 |
<WABA_ID>String |
Required.
WhatsApp Business Account ID. |
102290129340398 |
<BID_AMOUNT>int |
Required.
Maximum price per 1,000 message deliveries, expressed in your WABA currency's smallest unit (cents for USD, paise for INR, peso for MXN). See supported currencies for a list of currencies. |
87000 |
Calculating max-price amounts
The
Convert your desired per-delivery price to your WABA currency's smallest unitMultiply by 1,000 to express the value per 1,000 deliveries
bid_amount represents your max-price per 1,000 deliveries in your WABA currency's smallest unit. To convert from your desired per-delivery price:Example: To set a max-price of ?0.87 per delivery:
Convert to paise: 0.87 Rupees = 87 paiseMultiply by 1,000: 87 x 1,000 = 87,000
Set
bid_amount to 87000.Example: To set a max-price of $0.05 USD per delivery:
Convert to cents: $0.05 = 5 centsMultiply by 1,000: 5 x 1,000 = 5,000
Set
bid_amount to 5000.Metrics and billing
Messages sent with or without the max-price feature use the same Marketing Lite product type (SKU) for billing purposes.
Marketing messages sent with max-price appear in analytics with the following identifiers:
Pricing Analytics/<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=pricing_analytics: pricing_category = MARKETING_LITETemplate Analytics/<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=template_analytics: product_type = MARKETING_MESSAGES_LITE_API
Webhooks use lowercase
marketing_lite for pricing.category, while analytics APIs use uppercase MARKETING_LITE for pricing_category.Pricing analytics response example
Template analytics response example
For more details on metrics, see Viewing metrics.
Error codes
| Code | Message | Possible reasons and solutions |
|---|---|---|
|
131061 |
Marketing templates containing bid_spec are not supported by the Cloud API. To use templates with bid_spec, please use the Marketing Messages API for WhatsApp. |
You are sending a template with bid_spec to the Cloud API /messages endpoint. Send to the /marketing_messages endpoint instead. |
|
100 |
You need to sign the testing legal agreement before sending out messages. |
You have not signed the testing legal agreement. Please sign the agreement to gain access to this feature. |
For a full list of error codes, see Error codes.