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 UI

Via the Business Management API “Message Templates” endpoint

If 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.

Automatic creative optimizations

Automatic creative optimizations test variations with different creative treatments, and optimize marketing messages based on practices observed from high performing creatives. They can be disabled using the Template-level opt-out or WhatsApp business account-level opt-out, providing businesses flexibility and control over how creative enhancements are applied. These are similar to Advantage+ creative⁠ for ads.

Automatic creative optimizations like text extraction and highlighting have driven an average increase of 13.9%* in click-through rates (CTR).

This feature introduces creative variability for performance optimization, meaning the output may vary between messages even with the same input. This capability tests minor variations of your existing image header and automatically selects the variant getting the highest click-through rate over time, with no input needed from you. We are continuously exploring and testing new automatic creative optimizations to help maximize your campaign performance. As new variations become available, they may be applied to opted-in templates to drive better business results.

Image filtering

For some campaigns, Meta automatically applies the most effective filters to header images in order to enhance the images’ quality and appeal:

Headline extraction

For some campaigns, Meta extracts keywords or phrases from your message to create a headline for your body text to highlight key information.

Tap-target title extraction

For some campaigns, Meta extracts keywords or phrases from your message to create a title for the tap-target area to highlight key information.

Text formatting

For some campaigns, Meta updates the formatting of text (for example, removing unnecessary spaces, bolding phrases) to increase performance. No text content is changed - format only.

Coming soon

We are continuously exploring and testing new automatic creative optimizations to help maximize your campaign performance. While we expect to make these enhancements available in the future, our plans are subject to change.

Product extensions

Meta enhances single-image creatives by appending a set of additional catalog products users are likely to engage or convert with, creating more personalized and relevant experiences.

Auto promotion tag

For some campaigns, Meta will automatically extract the promotion tag, like “30% off”, “50% discount”, “Free shipping” from messages to create a promotion tag and put it into the image to highlight promotion information.

For some campaigns, Meta will apply colorful paddings to transform the image creative to the optimal aspect ratio to enhance visual appeal and improve media digestibility.

Link formatting (hyperlinks)

For some campaigns, Meta will transform any URL links in the message body by either shortening the link or applying markdown formatting (hyperlinks) to adjacent key phrases to improve message digestibility.

Paused or deprecated

We have paused the following automatic creative optimizations, and you should not expect these to be applied to your marketing messages. We will update documentation if we restart any of these in the future:

Image cropping: Meta automatically crops header images to an optimal dimension, ensuring your visuals are always perfectly framed without cutting off image text.

Text overlays: Meta automatically adds a text overlay onto your image using your message content.

Image animation: Meta automatically transforms your header image into an animated GIF.

Image background generation: Meta automatically generates a new image background.

Footnotes

*This finding is based on an AB test conducted with over 50 million delivered marketing messages sent by about 200 advertisers on MM API for WhatsApp between December 1, 2025, and January 7, 2026. It compared CTR for messages with automatic creative optimizations (ACO) applied to messages without any ACOs applied and the analysis results were statistically significant at 95% confidence.

Configure automatic creative optimizations (template-level)

All optimization features are enabled by default, but you can use the creative_features_spec object to specify which optimizations you want to enable (“opt-in”) or disable (“opt-out”) on a given template. To do this, set each optimization’s enroll_status property to either OPT_IN or OPT_OUT upon template creation, or when editing an existing template.

Request syntax

Use the POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates endpoint to configure automatic creative optimizations at a template level.

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
{
  "name": "<TEMPLATE_NAME>",
  "language": "<TEMPLATE_LANGUAGE_AND_LOCALE_CODE>",
  "components": [<TEMPLATE_COMPONENTS>],
  "degrees_of_freedom_spec": {
    "creative_features_spec": {
      "image_brightness_and_contrast": {
        "enroll_status": "OPT_OUT"
      },
      "image_touchups": {
        "enroll_status": "OPT_IN"
      },
      "add_text_overlay": {
        "enroll_status": "OPT_OUT"
      },
      "image_animation": {
        "enroll_status": "OPT_IN"
      },
      "image_background_gen": {
        "enroll_status": "OPT_IN"
      },
      "auto_promotion_tag": {
        "enroll_status": "OPT_IN"
      },
     "text_extraction_for_headline": {
       "enroll_status": "OPT_IN"
     },
     "text_extraction_for_tap_target": {
       "enroll_status": "OPT_IN"
     },
      "product_extensions": {
        "enroll_status": "OPT_OUT"
      },
      "text_formatting_optimization": {
        "enroll_status": "OPT_OUT"
      }
    }
  }
}

Use the GET /<TEMPLATE_ID> endpoint to retrieve automatic creative optimizations statuses at a template level.

Request syntax

GET /<TEMPLATE_ID>?fields=degrees_of_freedom_spec

Example response

{
  "degrees_of_freedom_spec": {
    "creative_features_spec": [
      {
        "key": "IMAGE_BRIGHTNESS_AND_CONTRAST",
        "value": { "enroll_status": "OPT_OUT" }
      },
      {
        "key": "IMAGE_TOUCHUPS",
        "value": { "enroll_status": "OPT_OUT" }
      },
      {
        "key": "ADD_TEXT_OVERLAY",
        "value": { "enroll_status": "OPT_IN" }
      },
      {
        "key": "IMAGE_ANIMATION",
        "value": { "enroll_status": "OPT_OUT" }
      },
      {
        "key": "IMAGE_BACKGROUND_GEN",
        "value": { "enroll_status": "OPT_OUT" }
      },
      {
        "key": "AUTO_PROMOTION_TAG",
        "value": { "enroll_status": "OPT_OUT" }
      },
      {
        "key": "TEXT_EXTRACTION_FOR_HEADLINE",
        "value": { "enroll_status": "OPT_OUT" }
      },
      {
        "key": "TEXT_EXTRACTION_FOR_TAP_TARGET",
        "value": { "enroll_status": "OPT_OUT" }
      },
      {
        "key": "PRODUCT_EXTENSIONS",
        "value": { "enroll_status": "OPT_IN" }
      },
      {
        "key": "TEXT_FORMATTING_OPTIMIZATION",
        "value": { "enroll_status": "OPT_IN" }
      }
    ]
  },
  "id": "123456789"
}

Configure automatic creative optimizations (WhatsApp Business Account-level)

All optimization features are enabled by default, but you can use the creative_features_spec object to specify which optimizations you want to enable (“opt-in”) or disable (“opt-out”) for the entire WhatsApp Business Account. To do this, set each optimization’s enroll_status property that you wish to modify to either OPT_IN or OPT_OUT.

Request syntax

Use the POST /<WHATSAPP_BUSINESS_ACCOUNT_ID> endpoint to configure automatic creative optimizations at a WhatsApp Business Account level.

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>
{
  "degrees_of_freedom_spec": {
    "creative_features_spec": {
      "image_touchups": {
        "enroll_status": "OPT_IN"
      },
      "image_animation": {
        "enroll_status": "OPT_IN"
      },
      "image_brightness_and_contrast": {
        "enroll_status": "OPT_IN"
      },
      "add_text_overlay": {
        "enroll_status": "OPT_IN"
      },
      "image_background_gen": {
        "enroll_status": "OPT_IN"
      },
      "auto_promotion_tag": {
        "enroll_status": "OPT_IN"
      },
      "text_extraction_for_headline": {
        "enroll_status": "OPT_IN"
      },
      "product_extensions": {
        "enroll_status": "OPT_IN"
      },
      "text_extraction_for_tap_target": {
        "enroll_status": "OPT_IN"
      },
      "text_formatting_optimization": {
        "enroll_status": "OPT_OUT"
      }
    }
  }
}

Request syntax

Use the GET /<WHATSAPP_BUSINESS_ACCOUNT_ID> endpoint to retrieve automatic creative optimizations statuses at a WhatsApp Business Account level.

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=degrees_of_freedom_spec

Example response

{
  "degrees_of_freedom_spec": {
    "data": [
      {
        "creative_features_spec": [
          {
            "image_brightness_and_contrast": "OPT_IN",
            "image_touchups": "OPT_IN",
            "add_text_overlay": "OPT_IN",
            "image_animation": "OPT_IN",
            "image_background_gen": "OPT_IN",
            "auto_promotion_tag": "OPT_IN",
            "text_extraction_for_headline": "OPT_IN",
            "product_extensions": "OPT_IN",
            "text_extraction_for_tap_target": "OPT_IN",
            "text_formatting_optimization": "OPT_IN"
          }
        ]
      }
    ]
  },
  "id": "1234567890"
}

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 lines

Messages with a media header (Image, Video, Document, Location, and GIF): truncated to 3 lines

Messages 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, unless you have disabled marketing messages on Cloud API.

Endpoint	Authentication
`/PHONE_NUMBER_ID/marketing_messages`	Developers can authenticate their API calls with the access token generated in the App Dashboard > WhatsApp > API Setup. If you are a business messaging service provider, you must authenticate with an access token with the `whatsapp_business_messaging` permission.

Request syntax

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/marketing_messages
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "<MESSAGE_TYPE>",
  "<MESSAGE_TYPE>": {
    <MESSAGE_CONTENTS>
  },
  <!-- Optional -->
  "product_policy": "<PRODUCT_POLICY>",
  "message_activity_sharing": <SHARE_MESSAGING_ACTIVITY?>
}

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.

Disable marketing messages on Cloud API

If your business has onboarded to MM API for WhatsApp, you can disable the ability to send Marketing category templates through the Cloud API /messages endpoint. When this option is activated, the /messages endpoint rejects Marketing category templates. You can decide whether to send marketing messages through the /marketing_messages endpoint or disable this option.

This setting has no effect on WhatsApp Business Accounts (WABAs) that have not started the MM API for WhatsApp onboarding process; it only takes effect on WABAs that have fully onboarded. WABAs that have started the onboarding process but have not signed the Terms of Service (ToS) may experience blocked marketing messages, as described in Fallback behavior on /marketing_messages.

Request syntax

Use the POST /<WHATSAPP_BUSINESS_ACCOUNT_ID> endpoint to enable or disable marketing messages on Cloud API.

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>
{
  "disable_marketing_messages_on_cloud_api": true | false
}

Set disable_marketing_messages_on_cloud_api to true to block Marketing category templates on the Cloud API /messages endpoint. Set to false to allow Marketing category templates on Cloud API (default).

Example request

The following request disables marketing messages on Cloud API for the specified WhatsApp Business Account.

curl 'https://graph.facebook.com/v25.0/102290129340398' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "disable_marketing_messages_on_cloud_api": true
}'

Example response

{
  "id": "102290129340398"
}

Request syntax

Use the GET /<WHATSAPP_BUSINESS_ACCOUNT_ID> endpoint to check the current value.

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=disable_marketing_messages_on_cloud_api

Example response

{
  "disable_marketing_messages_on_cloud_api": true,
  "id": "102290129340398"
}

Error response

If disable_marketing_messages_on_cloud_api is set to true and you attempt to send a Marketing category template through the Cloud API /messages endpoint, the API returns the following error:

{
  "error": {
    "message": "(#131063) Marketing templates disabled for Cloud API",
    "type": "OAuthException",
    "code": 131063,
    "error_data": {
      "messaging_product": "whatsapp",
      "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."
    },
    "fbtrace_id": "ABzNMWIqsLJ7hbj8xd5ytay"
  }
}

Fallback behavior on `/marketing_messages`

When disable_marketing_messages_on_cloud_api is set to true, the fallback to Cloud API for the /marketing_messages endpoint is also affected:

MM API ToS signed: The /marketing_messages endpoint works normally. No change in behavior.

MM API ToS not signed: Marketing template messages sent to /marketing_messages would normally fall back to Cloud API, but the fallback is now rejected with error 131063 because the opt-in blocks marketing templates on Cloud API.

To avoid this error, ensure your WABA has completed all onboarding requirements before enabling this setting.

Note: When the per-message product_policy is set to STRICT, no fallback to Cloud API is attempted regardless of the disable_marketing_messages_on_cloud_api setting. The fallback behavior described above only applies when product_policy is set to the default of CLOUD_API_FALLBACK.

Re-enable marketing messages on Cloud API

To restore the ability to send Marketing category templates through the Cloud API /messages endpoint, set disable_marketing_messages_on_cloud_api to false:

curl 'https://graph.facebook.com/v25.0/102290129340398' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "disable_marketing_messages_on_cloud_api": false
}'

This restores the default behavior — Marketing category templates are accepted on the /messages endpoint again.

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.

{
  "conversation": {
    "id": "<CONVERSATION_ID>",
    "origin": {
      "type": "marketing_lite"
    }
  },
  "pricing": {
    "billable": true,
    "pricing_model": "PMP",
    "category": "marketing_lite"
  }
}

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.

Did you find this page helpful?

Send Marketing Messages

Create marketing templates

Automatic creative optimizations

Image filtering

Headline extraction

Tap-target title extraction

Text formatting

Coming soon

Product extensions

Auto promotion tag

Image banner

Link formatting (hyperlinks)

Paused or deprecated

Footnotes

Configure automatic creative optimizations (template-level)

Request syntax

Request syntax

Example response

Configure automatic creative optimizations (WhatsApp Business Account-level)

Request syntax

Request syntax

Example response

Other optimizations

Text truncation

Send marketing template messages

Request syntax

Disable marketing messages on Cloud API

Request syntax

Example request

Example response

Request syntax

Example response

Error response

Fallback behavior on /marketing_messages

Re-enable marketing messages on Cloud API

Receiving message status webhooks

Receiving incoming messages

Fallback behavior on `/marketing_messages`