Marketing Messages API for WhatsApp

Reference for Meta's separate /marketing_messages product, which is not exposed by Dualhook's runtime or Embedded Signup configuration.

What MM API for WhatsApp Is

Not exposed by Dualhook: Dualhook's Embedded Signup v4 configuration does not request Marketing Messages Lite and the allowlisted runtime does not expose /marketing_messages. All examples on this page describe Meta's separate product and require a separately reviewed, customer-owned Meta app and authorization. Never substitute a dh_live_... key or a Dualhook-managed credential.

Marketing Messages API for WhatsApp (formerly "Marketing Messages Lite API", now generally available) is Meta's optimized send path for marketing template messages. It uses the same templates, the same phone numbers, and the same per-message billing as Cloud API — but routes sends through a parallel /marketing_messages endpoint that adds delivery and creative optimizations.

MM API is send-only. To receive incoming messages, status webhooks for non-marketing traffic, or send anything other than marketing templates, you continue to use Cloud API in parallel on the same phone number.

Cloud API Marketing Sunset

On October 13, 2026 Meta announced that Cloud API will stop supporting marketing messages. Service, authentication, and utility messages stay on Cloud API.

DateWhat changes
April 13, 2027Messaging accounts (WABAs) created on or after this date cannot send marketing messages through Cloud API, only through MM API. Accounts created before it keep Cloud API marketing until the global sunset.
October 13, 2027Global sunset: sending a marketing message through Cloud API /messages returns an error. Marketing messages must go through /marketing_messages or another Meta surface that supports them.

Meta's migration steps: accept the MM API terms, move the integration to /marketing_messages (Meta estimates about two weeks for most integrations), and route templates by their latest category, because utility templates reclassified as marketing must also go through MM API.

Feature Comparison vs Cloud API

CapabilityCloud APIMM API for WhatsApp
Send marketing templatesYesYes
Send authentication / utility / service templatesYesNo
Send freeform (text, image, etc.)Yes (inside CSW)No
Receive incoming messages and statusesYesNo
Quality-based delivery optimizationNoYes — up to ~9% higher delivery for high-engagement messages
Automatic creative optimizationsNoYes
Animated image (GIF) headerNoYes
Android app deep links on URL buttonsNoYes
Customizable TTL on marketing templatesNoYes (12 hours – 30 days)
TTL on auth/utility templatesYesN/A
Performance benchmarks vs similar businessesNoYes
Tailored creative recommendationsNoYes
Conversion metrics (Web/App)NoYes
Cost metrics (spend per template, per click, per delivery)YesYes
Basic metrics (sent, delivered, read, clicked, errors)YesYes
Local Storage supportYesYes
Formal compliance program supportYesYes
Max-price (beta)NoYes
OnboardingEmbedded SignupEmbedded Signup, Intent API, Intent UI

The /marketing_messages Endpoint

POST https://graph.facebook.com/<GRAPH_VERSION>/<PHONE_NUMBER_ID>/marketing_messages

The send payload is identical to Cloud API's /messages payload for template messages, with two MM-specific optional fields:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "template",
  "template": {
    "name": "<TEMPLATE_NAME>",
    "language": { "code": "<LANGUAGE_AND_LOCALE_CODE>" },
    "components": [ /* same shape as Cloud API */ ]
  },
  "product_policy": "CLOUD_API_FALLBACK",
  "message_activity_sharing": true
}
FieldDefaultPurpose
product_policyCLOUD_API_FALLBACKIf the WABA hasn't completed MM API onboarding, the message is automatically sent through Cloud API instead. Set to STRICT to disable this fallback (the call fails instead of falling back).
message_activity_sharingWABA-level defaultPer-message override of whether read/click events from this send are shared with Meta to improve optimization. Boolean.

Like /messages, the endpoint accepts a BSUID in recipient instead of a phone number in to; when both are set, to is used. Sends addressed by BSUID get no MM API delivery optimization.

Authentication must come from the business's own separately reviewed Meta integration. Dualhook does not reveal or authorize use of its customer-scoped BISU token for this endpoint.

Fallback Behavior to Cloud API

By default (product_policy omitted or set to CLOUD_API_FALLBACK), MM API will silently route a marketing template send through Cloud API if the WABA has not yet completed MM API onboarding. This makes MM API safe to wire up before the customer has signed the ToS.

Two important caveats:

  • If you have set disable_marketing_messages_on_cloud_api: true on the WABA (see below), the fallback is rejected with error 131063 because Cloud API marketing is disabled.
  • If you set product_policy: STRICT on the call, no fallback is attempted regardless of the disable flag.

Disable Marketing on Cloud API

Once a WABA has fully onboarded to MM API, you can require all marketing traffic to go through MM API by setting:

POST /<WABA_ID>
{ "disable_marketing_messages_on_cloud_api": true }

When this is true, attempting to send a MARKETING category template through /messages returns:

{
  "error": {
    "code": 131063,
    "message": "(#131063) Marketing templates disabled for Cloud API",
    "error_data": {
      "details": "Your template is categorized as Marketing, but marketing templates are currently disabled for your Cloud API configuration. To send this template, use the Marketing Messages API for WhatsApp or enable marketing templates on Cloud API by turning off disable_marketing_messages_on_cloud_api."
    }
  }
}

This setting only takes effect on WABAs that have fully onboarded (ToS signed). Setting it on a partially-onboarded WABA can produce blocked sends without a working fallback path. To check the current value:

GET /<WABA_ID>?fields=disable_marketing_messages_on_cloud_api

To re-enable Cloud API marketing, set the field back to false.

Route Templates by Category

A template's category can change after approval, for example from UTILITY to MARKETING when Meta finds the content promotional. Meta recommends choosing the endpoint per send from the template's latest category: MARKETING goes to /marketing_messages, every other category to /messages.

  • Keep a mapping of WABA ID, template ID, name, language, and latest category, filled from the Message Templates API. If an entry is missing, fetch the category before sending.
  • Update the mapping from the template_category_update webhook only after the change has completed, using new_category. Treat the scheduled-change notice as monitoring only and don't route on its correct_category.
  • Once the WABA is fully onboarded, set disable_marketing_messages_on_cloud_api: true. A template reclassified to marketing then fails on /messages with 131063: refresh its category and retry through /marketing_messages. If an appeal moves a marketing template to utility, /marketing_messages rejects it: refresh and retry through /messages. Retry only after a confirmed failure, and make retries idempotent.

Geographic Availability

RegionMM API behavior
EEA, UK, Japan, South Korea, Nigeria, South Africa, ThailandSends work, but no delivery optimizations, no click/conversion reporting, no per-user marketing limits. Metrics available only via Business Management API and WhatsApp Manager (not Ads Manager / Insights API).
United StatesMarketing messages to US recipients are blocked by Meta with error 131049 since April 1, 2025 — applies to both Cloud API and MM API. US-based business numbers can still send to non-US recipients.
Russia, BelarusMM API works since June 20, 2025, but with no delivery optimization for sends from Russian or Belarusian business profiles or payment methods, and no click/conversion reporting for sends from or to numbers in these countries.
Cuba, Iran, North Korea, Syria, Venezuela, Crimea, Donetsk, LuhanskCannot onboard, cannot send. Applies platform-wide.
Everywhere elseFull feature set.

Status Webhooks

MM API sends emit the same sent / delivered / read status webhooks as Cloud API, but the pricing object distinguishes them:

"pricing": {
  "billable": true,
  "pricing_model": "PMP",
  "type": "regular",
  "category": "marketing_lite"
}

For Cloud API marketing sends, pricing.category is marketing; for MM API sends it is marketing_lite. On v24.0 and later, Meta omits the conversation object unless the message was sent inside an open free entry point window. When it is present, conversation.origin.type uses the same value.

If you want to attribute outgoing message IDs back to their send path (e.g. for billing reconciliation), log which endpoint each wamid was returned from at send time and join against the webhook's id field.

Incoming Messages (Send-Only)

MM API does not deliver incoming messages. The messages field in webhooks for inbound user messages always comes through Cloud API's webhook subscription. In Dualhook setups, this is delivered directly to your endpoint via Webhook Override — there is no separate MM API inbound channel to subscribe to.

Errors Specific to MM API

CodeMeaningFix
131049Marketing messages cannot be delivered to US recipientsSuppress US wa_ids before sending
131063Marketing templates disabled for Cloud APIEither send via /marketing_messages or set disable_marketing_messages_on_cloud_api: false
131061Templates with bid_spec (max-price) cannot be sent via Cloud APISend via /marketing_messages instead
131050Recipient stopped marketing messages from your businessSuppress the recipient and respect the user_preferences webhook

Dualhook's Stance

Dualhook supports marketing templates through the standard Cloud API /messages route at api.dualhook.com, so that route is subject to the Cloud API marketing sunset. The Runtime API has no /marketing_messages route and cannot read or set marketing_messages_onboarding_status or disable_marketing_messages_on_cloud_api, and the dashboard has no MM API onboarding. To use MM API, accept its terms in WhatsApp Manager and send through your own reviewed Meta app. Dualhook does not request MM Lite terms, ad assets, ads_read, or the MM Lite feature during Embedded Signup. Meta-generated MM_LITE_TERMS_SIGNED management events may still be observed and recorded as lifecycle metadata, but Dualhook does not initiate that event or enable the product.

Related

  • Marketing MessagesMarketing template messaging through Dualhook's standard Cloud API runtime, plus boundaries for Meta's separate MM API product.
  • MM API OnboardingReference for MM API onboarding outside Dualhook's managed configuration. Dualhook does not request Marketing Messages Lite.
  • Marketing Conversion TrackingMeasure conversions from marketing messages with Meta Pixel, Conversions API, and the Meta SDK. Includes fbclid handling, the click-event webhook, and Android deep-link attribution.
  • Marketing Creative OptimizationsConfigure Meta's automatic creative optimizations on MM API marketing templates: creative_features_spec at template and WABA level, opt-in/opt-out per key.
  • Marketing Max-Price (Beta)Set a maximum price per marketing message delivery on MM API for WhatsApp using bid_spec. Includes per-message multiplier, reach estimation, and rollout phases.
  • PricingDualhook subscription plans, what is included, and how pricing relates to Meta messaging fees.
Browse more docsStart Free Trial