Meta / Facebook Developer Docs Mirror

Appearance

Mirrored from https://developers.facebook.com/documentation/business-messaging/messenger-platform/marketing-messages-on-messenger/additional-resources

Marketing Message API for Messenger Changelog ​

Updated: Jun 30, 2026

June 30, 2026 ​

POST /act_<AD_ACCOUNT_ID>/message_campaign

Default Budget Mode ​

  • Added support for creating a marketing messages campaign without daily_budget or lifetime_budget. When neither field is provided, Meta may set an estimated daily budget cap for the campaign.
  • You can still provide daily_budget or lifetime_budget. If the budget you provide is lower than the generated budget reference for the campaign, the API may return a non-blocking warning. Your campaign will still use the budget you provided.

June 11, 2026 ​

POST /<PAGE_ID>/messaging_customer_base/unsubscribe

Unsubscribe API ​

  • Added support for unsubscribing matched users from a Page's marketing messages audience by phone, email, PSID, or subscriber token.
  • This endpoint unsubscribes users at the Page level and is different from removing users from a Custom Audience.

POST /act_<AD_ACCOUNT_ID>/message_campaign

Campaign Scheduling Fields ​

  • Added support for optional start_time and end_time Unix timestamp fields when creating a marketing messages campaign.
  • You can provide start_time, end_time, both, or neither. Lifetime-budget campaigns default to a 30-day end window from start_time, or from campaign creation time when start_time is also omitted.

POST /act_<AD_ACCOUNT_ID>/messages

Conversation Gap Send Control ​

  • Added support for optional min_conversation_gap_seconds to prevent sending when recent organic Messenger thread activity between the Page and the end user is inside the requested gap.
  • When this control prevents a send, the API returns error code 2300052 with the message This person is not available right now.

May 22, 2026 ​

POST /act_<AD_ACCOUNT_ID>/message_campaign

Meta Pixel Attribution Support for Campaign Creation ​

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

GET /<MESSAGE_CAMPAIGN_ID>

Pixel ID Returned in Campaign Query ​

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

GET /<MESSAGE_CAMPAIGN_ID>/insights

Meta Pixel Offsite Conversion Insights ​

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

May 15, 2026 ​

POST /act_<AD_ACCOUNT_ID>/messages

Recipient Eligibility Improvements ​

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

May 14, 2026 ​

POST /act_<AD_ACCOUNT_ID>/messages

More Granular Campaign Spending Limit Error Codes ​

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

May 12, 2026 ​

GET /act_<AD_ACCOUNT_ID>/message_delivery_estimate

Estimation API Fully Rolled Out to Open Beta ​

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

POST /act_<AD_ACCOUNT_ID>/message_campaigns

Fixed Race Condition Causing Error 4017070 on Campaign Creation ​

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

POST /act_<AD_ACCOUNT_ID>/messages

Postback Button Payload Fix ​

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

APP Button URLs Restricted to HTTPS Only ​

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

GET /act_<AD_ACCOUNT_ID>/campaigns

MAPI-D Campaigns Filtered from Ads Manager ​

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

May 6, 2026 ​

Partner Billing Onboarding Flow Launched ​

  • 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).

May 5, 2026 ​

POST /act_<AD_ACCOUNT_ID>/messages

marketing_message_delivery_failed Webhook Coverage Improvement ​

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

New Pacing Info Unavailable Error Code ​

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

default_action URL Fix for Generic Template ​

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

Video Rendering Fix for Remote URL API ​

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

1-Hour Warm-Up Enforced for All Advertisers ​

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

DELETE /act_<AD_ACCOUNT_ID>/customaudiences

Custom Audiences API REMOVE_USER Now Preserves Opt-In Status ​

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

May 1, 2026 ​

Estimation API ​

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

April 24, 2026 ​

Error Code

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

April 10, 2026 ​

POST /act_<AD_ACCOUNT_ID>/messages

Frequency Capping Now Enforced on All Marketing Messages ​

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

Daily-Budget Campaign End-Time Bug Fix ​

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

Creative Validation Fix ​

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

POST /act_<AD_ACCOUNT_ID>/message_campaign

Daily-Budget Campaigns No Longer Have Artificial End 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.

Webhooks Now Fire for Newly Created Active Campaigns ​

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

Webhook Payload Ad Account ID Fix ​

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

April 8, 2026 ​

POST /act_<AD_ACCOUNT_ID>/message_campaign

POST /act_<AD_ACCOUNT_ID>/campaigns

POST /act_<AD_ACCOUNT_ID>/adsets

POST /act_<AD_ACCOUNT_ID>/ads

Improved Error Codes for Campaign Creation ​

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

March 31, 2026 ​

POST /act_<AD_ACCOUNT_ID>/messages

Delivery Failed Webhook Coverage Improvement ​

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

Pacing Errors Now Surfaced With Specific Error Codes ​

  • 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).

March 26, 2026 ​

POST /act_<AD_ACCOUNT_ID>/message_campaign

POST /act_<AD_ACCOUNT_ID>/campaigns

POST /act_<AD_ACCOUNT_ID>/adsets

POST /act_<AD_ACCOUNT_ID>/ads

Region Deny Rule for Campaign Creation ​

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

March 19, 2026 ​

POST /act_<AD_ACCOUNT_ID>/messages

Specific Error Code for Recipient Not Available ​

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

March 16, 2026 ​

GET /<CAMPAIGN_ID>/insights

Insights time_range and date_preset Support ​

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

GET /<APP_ID>/

Business Manager No Longer Required for Onboarding ​

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

POST /act_<AD_ACCOUNT_ID>/messages

Improved Error Codes for Message Sending Failures ​

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

Pacing Error Responses Now Include Remaining Wait Time ​

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

POST /<PAGE>/notification_message_tokens

New Rate Limit Error Code for Subscription Token Queries ​

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

March 9, 2026 ​

POST /act_<AD_ACCOUNT_ID>/messages

Coupon Code Greeting Personalization Enabled ​

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

March 5, 2026 ​

Asset-Based (UAT) Onboarding Flow Launched Globally ​

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

January 22, 2026 ​

Webhook Recipient-ID Validation Fix ​

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

January 17, 2026 ​

POST /act_<AD_ACCOUNT_ID>/messages

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

January 6, 2026 ​

POST /act_<AD_ACCOUNT_ID>/messages

Personalized Greetings for Freeform Messages ​

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

November 20, 2025 ​

POST /act_<AD_ACCOUNT_ID>/messages

Introducing Quick Replies ​

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

Webhooks for Message Deliveries and Clicks ​

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

Disable Usage of Postback Buttons With Video Attachment ​

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

November 7, 2025 ​

POST /act_<AD_ACCOUNT_ID>/customaudiences

Facebook Page in Custom Audience API ​

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

POST /<PAGE>/notification_message_tokens

Parameter to Remove Duplicate Recipients in 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.

November 6, 2025 ​

POST /act_<AD_ACCOUNT_ID>/messages

Introducing Coupon Codes and LTO Format ​

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

November 3, 2025 ​

POST /act_<AD_ACCOUNT_ID>/messages

Introducing the Image Grid Format ​

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

October 20, 2025 ​

POST /act_<AD_ACCOUNT_ID>/messages

Improved Reliability for Message Sending ​

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

Webhooks for Message Sending ​

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

Remove Per-Campaign Send Restriction ​

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

October 6, 2025 ​

POST act_<AD_ACCOUNT_ID>/campaigns

CTM Ads Is Now Available to All Users ​

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

POST /act_<AD_ACCOUNT_ID>/messages

Postback Support ​

  • 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

September 26, 2025 ​

POST /act_<AD_ACCOUNT_ID>/messages

Add personalization macros ​

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

September 8, 2025 ​

POST /act_<AD_ACCOUNT_ID>/customaudiences

Upload Status Webhook for Custom Audience API ​

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

GET /<PAGE_ID>/notification_message_tokens

Increase Limit for Fetching Subscriber Tokens ​

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

Fix Missing Subscriber Tokens With Filters ​

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

POST /act_<AD_ACCOUNT_ID>/messages

Fix Missing Marketing Message From Page's Inbox ​

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

August 25, 2025 ​

POST /act_<AD_ACCOUNT_ID>/messages

Allow the Creation of Marketing Messages Without a Button ​

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

Improved Message Sending for Custom Audience Subscribers ​

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

POST /act_<AD_ACCOUNT_ID>/message_campaign

Check Terms of Service During Campaign Creation ​

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

August 11, 2025 ​

POST /act_<AD_ACCOUNT_ID>/messages

Cooldown Between Message Sends ​

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

July 31, 2025 ​

POST /<CUSTOM_AUDIENCE_ID>/users

GET /<PAGE_ID>/notification_message_tokens

Custom Audience Segmentation For Subscription Tokens ​

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

GET act_<AD_ACCOUNT_ID>/insights

Measure a Marketing Messages on Messenger Campaign Performance ​

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

July 1, 2025 ​

Introducing the Marketing Message API for Messenger!

Unofficial mirror for reference/search purposes. All content originates from developers.facebook.com — see the source link at the top of each page. Machine-readable indexes: llms.txt · llms-full.txt · About

Content © Meta Platforms, Inc. · Built by Arjun Aditya