MM API Onboarding

Overview

Onboarding to Marketing Messages API for WhatsApp is a one-time per-WABA action: the customer's business signs Meta's MM API Terms of Service. Once signed, the WABA can send marketing templates through /marketing_messages — see Marketing Messages API for WhatsApp for the send mechanics.

Onboarding is non-destructive: the existing Cloud API setup keeps working, the same business phone numbers and templates remain in place, and you can keep sending marketing through Cloud API alongside MM API until you choose to disable that path.

Prerequisites

To be eligible for MM API onboarding, the WABA must:

• Be active and not restricted from messaging due to policy violations.
• Have a tax country and an owner business country that are not in sanctioned regions (Cuba, Iran, North Korea, Syria, Crimea, Donetsk, Luhansk).
• Have at least one phone number registered on Cloud API. MM API does not register new numbers — it reuses the Cloud API registration. Numbers not registered on Cloud API cannot be used for MM API.

App-side, the partner app needs advanced access for:

• whatsapp_business_messaging — to call /marketing_messages
• whatsapp_business_management — to manage WABAs, phone numbers, and templates
• ads_read (optional) — required only to call the Insights API for conversion metrics

Check Eligibility

The canonical eligibility check is the marketing_messages_onboarding_status field on the WABA:

curl 'https://graph.facebook.com/<GRAPH_VERSION>/<WABA_ID>?fields=marketing_messages_onboarding_status' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

{
  "id": "102290129340398",
  "marketing_messages_onboarding_status": "ELIGIBLE"
}

Possible values include ELIGIBLE, ONBOARDED, and others — see Meta's WhatsApp Business Account API reference for the full list.

For partners discovering eligible WABAs across many customers in one call, use the Client WABAs endpoint with a filter:

curl -g 'https://graph.facebook.com/<GRAPH_VERSION>/<BUSINESS_PORTFOLIO_ID>/client_whatsapp_business_accounts?filtering=[{"field":"marketing_messages_onboarding_status","operator":"IN","value":["ELIGIBLE"]}]' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

A legacy field marketing_messages_lite_api_status exists for the same purpose but is being deprecated in version 24.0. Use marketing_messages_onboarding_status for new code.

Three Onboarding Paths

Embedded Signup with marketing_messages_lite

For partners onboarding customers programmatically, MM API piggybacks on the standard Embedded Signup flow. Two configuration changes:

1. Facebook Login for Business config:

• Assets: WhatsApp accounts (do not select Ad accounts, Pages, Catalogues, Pixels, or Instagram accounts)
• Permissions: whatsapp_business_management, whatsapp_business_messaging, optionally ads_read

2. Add the marketing_messages_lite feature to the popup launch payload:

{
  "config_id": "<CONFIG_ID>",
  "response_type": "code",
  "override_default_response_type": true,
  "extras": {
    "featureType": "whatsapp_business_app_onboarding",
    "sessionInfoVersion": "3",
    "features": [
      { "name": "marketing_messages_lite" }
    ],
    "version": "v3"
  }
}

The OAuth code returned can be exchanged for a Business Integration System User access token in the normal way. The resulting token has the permissions needed to send via MM API and (if ads_read was granted) to fetch metrics from the Insights API.

ToS Signed Webhook

The preferred onboarding-completion signal is an account_update webhook with event MM_LITE_TERMS_SIGNED, fired once the customer's business signs the MM API ToS. Available since September 8, 2025.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<SOLUTION_PROVIDER_BUSINESS_ID>",
      "time": "<WEBHOOK_TIMESTAMP>",
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "MM_LITE_TERMS_SIGNED",
            "waba_info": {
              "owner_business_id": "<BUSINESS_PORTFOLIO_ID>",
              "waba_id": "102290129340398"
            }
          }
        }
      ]
    }
  ]
}

When you see this webhook for a given WABA, it is safe to start sending through /marketing_messages for that WABA. The webhook fires once per WABA under the portfolio, not once per portfolio.

Legacy: AD_ACCOUNT_LINKED Webhook

Before the ToS-signed webhook existed, MM API onboarding was tracked via an account_update webhook with event AD_ACCOUNT_LINKED. This webhook still fires but is now considered legacy — Meta no longer grants partners access to the linked ad account, so the ad_account_id it carries is read-only background metadata.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": "<WEBHOOK_TIMESTAMP>",
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "AD_ACCOUNT_LINKED",
            "waba_info": {
              "waba_id": "102290129340398",
              "ad_account_id": "<AD_ACCOUNT_ID>",
              "owner_business_id": "<BUSINESS_PORTFOLIO_ID>"
            }
          }
        }
      ]
    }
  ]
}

For new code, treat MM_LITE_TERMS_SIGNED as the source of truth and use AD_ACCOUNT_LINKED only as a fallback for legacy reporting.

What Onboarding Creates

When a business onboards to MM API, Meta creates read-only ad accounts under their business portfolio, one per WABA, synced to the WABA's marketing templates. These ad accounts exist purely as a technical construct so:

• Marketing templates and their performance show up in Ads Manager's "Marketing Messages" tab
• The Insights API can return per-template metrics including conversion events
• Conversions reported via Pixel/Conversions API/Meta SDK can be attributed back to the originating marketing message

Marketing teams are not Ads teams — the "Ads" terminology here is technical scaffolding only. The business does not run ads through these accounts and partners do not get access to spend, billing, or campaign editing.

Template-to-ad sync takes up to 10 minutes per new template. Templates that go unused for more than 7 days require another 10-minute sync after the first reuse. Wait that long after creating a new marketing template before sending production traffic with it — sending too soon can produce errors or skip optimization/measurement.

Event Activity Sharing

Once onboarded, message status events (delivered, read, clicked) are automatically shared with Meta to optimize delivery. Meta does not sell this data; it is used solely for marketing-message optimization.

To disable globally for a WABA, toggle "Share event activity" off in WhatsApp Business Account settings.

To override per send, include "message_activity_sharing": false (or true) on the /marketing_messages request body. The per-message value overrides the WABA-level default for that single send only.