Marketing Message API for Messenger Changelog

• Added support for the optional pixel_id parameter when creating a marketing messages campaign. Partners can provide a Meta Pixel ID to enable offsite conversion attribution for the campaign.
• If pixel_id is not provided and the ad account has exactly one active accessible pixel, Meta may use that pixel for attribution. If the ad account has no active pixels or more than one active pixel, the campaign is still created without pixel tracking.
• To avoid ambiguity, provide pixel_id explicitly when you want offsite conversion attribution.

• Added support for querying the pixel associated with a marketing messages campaign through adset{promoted_object{pixel_id}}.
• Partners can use this field to confirm whether a campaign has a Meta Pixel configured for offsite conversion attribution.

• Added support for querying website conversion events, website purchase conversion value, and website purchase ROAS attributed to marketing messages campaigns.
• Query offsite conversion metrics with fields=actions,action_values,website_purchase_roas, action_breakdowns=action_type, and a filtering parameter that includes the supported offsite_conversion.fb_pixel_* action types.
• Supported action types include offsite_conversion.fb_pixel_purchase, offsite_conversion.fb_pixel_add_to_cart, offsite_conversion.fb_pixel_initiate_checkout, offsite_conversion.fb_pixel_lead, offsite_conversion.fb_pixel_view_content, offsite_conversion.fb_pixel_custom, offsite_conversion.fb_pixel_complete_registration, offsite_conversion.fb_pixel_search, offsite_conversion.fb_pixel_add_payment_info, and offsite_conversion.fb_pixel_add_to_wishlist.
• No partner action is required for existing campaign delivery metrics.

• Improved recipient eligibility validation for the Send API. Sends to recipients determined to be ineligible will now be rejected with a RECIPIENT_UNAVAILABLE error.

• Improved the error codes returned when campaign spending limits are reached, providing more accurate and specific error responses. No partner action is required.

• The Estimation API is now available to all partners. A configuration issue that was blocking ad-account-level access has been resolved.

• Fixed an intermittent error (code 4017070) that could occur when creating campaigns via the /message_campaigns endpoint.
• The issue was caused by a timing race during Custom Audience association. If you experienced this error, you should no longer see it.

• Fixed a bug where postback button clicks delivered incorrect payload data in webhook events.
• Postback webhooks now correctly return the user-defined payload value specified in the message template.

• All APP button URLs in template messages now enforce HTTPS-only. Requests using non-HTTPS URL schemes will be rejected.
• This is a security hardening change. Ensure all APP button CTA URLs use the https:// scheme.

• Campaigns created via the Marketing Messages API are now filtered out of the Ads Manager campaigns list by default.
• This change reduces confusion for advertisers who manage marketing message campaigns through the API and see unrelated entries in Ads Manager.

• Launched a new Partner Billing Flow (Flow 3) for the Marketing Message API for Messenger, allowing partners to bill marketing message sends to their own ad account instead of the client’s.
• The flow uses the same SUAT and paid_marketing_messages permission as Flow 1 (Business Portfolio Flow). After the client completes login, the partner connects their own ad account to the client’s Business Integration System User (BISU) by calling the new POST https://api.facebook.com/system_accounts/<BISU_ID>/asset-connections endpoint.
• Requires the business_management permission in addition to the standard MAPI-D permissions; complete App Review for business_management before serving clients with this flow.
• See the updated onboarding documentation for full setup instructions, including the asset-connections endpoint call pattern (host, version, body format).

• Improved marketing_message_delivery_failed webhook coverage to cover the majority of errors during the async message sending phase.

• New error code 2300028 is returned when campaign pacing information is not yet ready at send time.
• Verify that the ad account and payment method are in good status. Applications should retry after 1 hour when receiving this error.

• Card and image taps in Generic Template messages now correctly open the default_action URL per the API specification, instead of the first button URL.
• Fixed a bug where default_action incorrectly required a title field.

• Videos uploaded via the Remote URL API now render correctly in Messenger, resolving cases where videos failed to display.

• All advertisers now observe the standard 1-hour warm-up period before sending marketing messages after campaign creation. Previously, some advertisers were exempt from this warm-up requirement.

• When you send a DELETE/REMOVE_USER request for a Custom Audiences API subscriber, the user is now removed from the custom audience while their overall marketing message opt-in remains intact.
• Previously, REMOVE_USER triggered a full opt-out from all marketing messages.

• Enhanced estimates calculation to consider per recipient country pricing, billing constraints etc., producing more accurate delivery and cost estimates. More details: estimates API

• Improved Error Codes for Message Sending Failures, added more explanation for the F-cap error

• Marketing message frequency caps are now enabled and enforcing on all sends. Three independent rules are applied:
  • Weekly cap: A message is blocked if the user’s marketing-message-to-organic-threads ratio exceeds 20% over the trailing 7 days (unless the user received zero marketing messages that week).
  • Daily cap: A message is blocked if the user’s marketing-message-to-organic-threads ratio exceeds 40% over the trailing 1 day (unless the user received zero marketing messages that day).
  • Minimum organic threads: A message is blocked if the user has not had a minimum number of organic conversation threads between consecutive marketing messages (unless the user’s last organic activity was more than 7 days ago).
• Messages that exceed frequency caps will be blocked and the API will return one of the following error codes:
  • WEEKLY_MM_LOAD_CAP_REACHED — the weekly cap was exceeded.
  • DAILY_MM_LOAD_CAP_REACHED — the daily cap was exceeded.
  • MIN_ORGANIC_THREAD_NOT_REACHED — the minimum organic threads requirement was not met.
• Applications should handle these error codes and avoid immediately retrying the same recipient, as the cap will remain in effect until the user’s organic messaging activity changes.

• Fixed a bug where daily-budget campaigns were bypassing campaign end-time enforcement, causing messages to be sent after their campaign end times.
• Daily-budget campaigns now correctly stop sending when their end time is reached.

• Fixed a bug where campaigns without a valid message payload were incorrectly passing the creative validation check.
• Campaigns without a valid message payload are now correctly rejected at send time.

• Daily-budget campaigns are no longer assigned an automatic 30-day end time at creation.
• Daily-budget campaigns now run indefinitely until manually paused or stopped, matching standard Ads behavior.

• Fixed a bug where message campaign and message campaign group webhooks were not firing for campaigns created with an active run status.
• Webhooks now correctly trigger on both creation and update of active campaigns.

• Fixed a bug where the AD_ACCOUNT webhook payload was emitting the wrong ad account ID.
• The webhook now correctly returns the legacy/payment ad account ID, consistent with other API responses.

• Fixed a bug where specific error codes for campaign creation deny rules (creative-reused, TOS-not-signed) were not being returned correctly, causing callers to receive generic errors.
• New API error codes 2300064–2300067 now correctly surface to partners.

• Improved the marketing_message_delivery_failed webhook coverage to report all message drops during the async message sending stage.

• The following error codes are now returned when a message send is rejected due to limits:
  • 2300069: Campaign lifetime budget reached.
  • 2300070: Campaign daily budget reached.
  • 2300071: Pacing limit reached.
  • 2300072: Account spend cap reached.
  • 2300073: Account daily spending limit reached.
  • 2300074: Prepay balance depleted.
  • 2300075: Business stored balance depleted.
  • 2300076: Daily spending limit reached.
  • 2300077: Flex billing limit reached.
  • 2300078: Brand extended credit limit reached.
  • 2300079: Daily spending limit reached.
  • 2300068: Default fallback for other pacing limits not applicable to Marketing Messages.
• These replace previously generic error responses, enabling partners to programmatically determine the exact reason for rejections and take appropriate action (e.g., pause campaigns, increase budgets, or wait for daily limits to reset).

• Campaign creation is now blocked for ad accounts in non-supported regions at the message campaign, message set, and message level.
• Each layer returns a clear “region not supported” error instead of failing silently or returning a generic error.

• The Send API now returns error code 1893047 (RECIPIENT_NOT_AVAILABLE) instead of a generic internal error when the recipient is not available for receiving the message.
• This can occur due to various reasons such as account issues or platform enforcement actions.

• The time_range and date_preset parameters now work for all metrics on the insights endpoint.

• We have launched a new onboarding flow where Business Manager access is no longer required for using the Marketing Message API for Messenger.
• The business-onboarding documentation has been updated with guidance on how to choose the right onboarding flow for your app, along with detailed setup instructions for each flow.

• New specific error codes have been introduced to provide clearer feedback when message sending fails:
  • 2300018 (ATTACHMENT_SAVE_FAILURE): Returned when an attachment fails to save during message processing.
  • 2300027 (ATTACHMENT_REUSE_NOT_ALLOWED): Returned when attempting to reuse an attachment that is not permitted for reuse.
  • 2300052 (RECIPIENT_UNAVAILABLE): Returned when a recipient is no longer reachable or available to receive marketing messages.
• These replace previously generic error codes, enabling more precise troubleshooting.

• When a message send is rejected due to pacing limits, the error response now includes a remaining_seconds field in error_data.
• This allows your application to programmatically determine how long to wait before retrying, rather than relying on fixed backoff strategies.

• A new error code 2300080 is now returned when the Subscription Tokens API rate limit is exceeded.
• This replaces the generic TOO_MANY_CALLS error, making it easier to distinguish token query rate limits from other API rate limits.

• Personalization macros (e.g., {{first_name}}) are now enabled on the coupon-code pre-message greeting for coupon-template marketing messages.

• The asset-based (UAT) onboarding flow without Business Portfolio requirement for the Marketing Message API for Messenger is now available to all Partner Apps.
• Partners can now complete asset-based (UAT) onboarding self-service.

• Fixed a bug where click and read webhooks were emitting recipient_id=0 when the page-scoped ID was null, causing webhook delivery to silently fail for partners.
• Webhooks now correctly pass null instead, preventing validation failures.

• Freeform templates now support buttons with deeplinks so that users can seamlessly navigate to specific destinations or features within your app.

• Freeform templates now support adding a greeting which shows up as a separate message before the marketing message.
• Businesses can use this greeting to create a more engaging conversational experience, as well as make use of the {{first_name}}, {{last_name}}, and {{full_name}} macros.
• For implementation details please see the documentation.

• We are excited to introduce Quick Replies for the Marketing Message API for Messenger.
• Quick replies let you display up to 13 customizable buttons in a Messenger conversation, each with a title and optional image, shown above the message composer.
• They can be used to prompt users for specific actions or information, including text responses, phone number, or email address.
• When a user taps a quick reply, the buttons disappear and the selected response is sent to your webhook along with any associated payload.

• The Marketing Message API for Messenger now supports webhooks for message delivery and click events.
• The new message delivery webhook notifies your application when a marketing message is successfully delivered to at least one user’s Messenger client.
• The click webhook sends a notification when a user clicks on a marketing message, enabling real-time tracking of user engagement.

• Postback buttons cannot be used with video attachments due to restrictions with the template.

• You can now access the messenger_marketing_messages_page field in the Custom Audiences API for Marketing Messages custom audiences.
• Returning the associated Facebook Page in the Custom Audience API helps ensure you use the correct Page Access Token when making queries with the Subscription Tokens API.

• You can now obtain a single token per recipient by using the do_not_return_duplicates parameter in the Subscription Tokens API.
• In the Recurring Notifications API, recipients may have multiple tokens if they subscribe to different Topics. This filter helps prevent sending multiple Marketing Messages to the same recipient.

• We are excited to announce the launch of the coupon codes and limited time offers (LTO) message formats.
• You can now send marketing messages that feature a coupon, with the option to include an expiration time and display a running timer.
• For additional details please see the documentation.

• With the addition of this new format you can now showcase several images in a grid pattern within your marketing message.
• To do so, include the image_urls parameter in your message payload and specify the images you would like to display.
• For more details please visit the documentation.

• Improved the reliability of sending direct marketing messages using the Marketing Message API for Messenger.
• Implemented more descriptive and explicit error messages to improve troubleshooting and transparency.

• We are excited to announce the launch of the message send status webhook feature.
• After a page sends a marketing message, your application can now receive a webhook notification confirming the message has been sent.
• For setup and additional details please visit the documentation.

• Previously, campaigns were limited to sending only one marketing message to a subscriber within a 90-day period.
• This restriction has now been lifted, allowing the same campaign to send multiple messages to the same subscriber in a 90-day window.

• Click-to-Messenger (CTM) Ads supply has successfully completed its experimentation phase and is now available to all users using Marketing Messages on Messenger.
• With this launch, businesses can expect a higher rate of subscriber growth through the opt-in flow.

• We have enabled postback support for Marketing Messages ensuring that a user’s action on a marketing message button will be sent back to the message thread.
• To enable postback, clients can setup a webhook and add it onto their app and when the button is clicked an event will be sent to that webhook

• Enable personalization macros to the title and subtitle fields for all formats. {{first_name}}, {{last_name}}, and {{full_name}} can be added into the title and subtitle strings to enable personalized marketing messages. For carousel, each element can have a personalized title and subtitle. Buttons do not have personalization enabled.

• When uploading a list of subscribers using the Custom Audience API, we now support a webhook that triggers when the subscriber upload and matching process is complete.
• This can be used to keep track of when a created custom audience is ready to use.

• Increase the page limit from 100 to 1000.
• Increase the endpoint request limit from 200 per hour per DAU to 1000 per hour per DAU.
• As a result of these changes, the maximum number of subscriber tokens that can be fetched within a period of 1 hour from 20,000 per DAU to 1,000,000 per DAU.

• Previously, filtering subscription tokens by custom audience IDs did not return any tokens due to restrictive filtering logic.
• Using custom audience ID filters will now correctly return all matching tokens.

• Due to privacy reasons, marketing messages sent to custom audience subscribers were not be visible to the page after delivery.
• Once the user responds to these messages, these messages will now become visible to the page.

• When sending a marketing message, it is no longer necessary for the message payload attachment to include a button.

• Increase the proportion of custom audience subscribers which are eligible to receive a marketing message by 10%.

• Return an error response during campaign creation when the business has not signed the Marketing Message API for Messenger Terms of Service.

• The subscription_token message sending cooldown has been updated from 24 hours to 12 hours. This means marketing messages sent using the same subscription_token now require only a 12-hour wait between sends, allowing for more frequent communication with users.

• When uploading a list of subscribers via /<CUSTOM_AUDIENCE_ID>/users in the Custom Audience API, the corresponding Custom Audience ID(s) will be included in the subscription token’s custom_audience_ids field. Note that a single subscription token can be associated with multiple custom audience uploads.
• You can filter subscription tokens by one or more Custom Audience IDs using the optional custom_audience_ids query parameter on the /<PAGE_ID>/notification_message_tokens endpoint.
• To safeguard user privacy, the /<PAGE_ID>/notification_message_tokens endpoint will only return subscription tokens for a given Custom Audience if there are 100 or more matched users in that audience upload. If fewer than 100 users match, tokens for that Custom Audience will be excluded from the response.

• Insights under an ad account can be obtained by the act_<AD_ACCOUNT_ID>/insights endpoint