December 4, 2018


  • Page-level Subscription Messaging Permission: If your app was granted the subscription messaging permission at the app-level, you should migrate to Page-level permission as soon as possible, however, as we continue to review our Subscription Messaging policies, developers provided access to send messages via app-level permissions may continue to do so until further notice.

September 27, 2018

Messenger Platform Release

  • Persona API (Beta): This new API introduces the concept of "personas" to the Messenger Platform, which allows you to invoke different identities for your bot in-thread. When a persona is invoked, the user icon and display name for the bot is switched. The Page name continues to be shown in the header of the thread.
  • Customer Chat Wordpress Plugin: The official Messenger Customer Chat plugin has been published on
  • Message Tags: The BUSINESS_PRODUCTIVITY message tag is now available for sending non-promotional, business-related updates outside the 24+1 standard messaging window. The restriction on which templates may be sent using message tags has also been removed. Tagged messages may now use any template, as well as text.
  • Platform Release Versioning: As of this release, we will no longer be assigning version numbers to Messenger Platform releases to avoid confusion with Graph API version numbering, and to enable a more frequent release cadence.

July 26, 2018

Breaking Change Notice

  • User Profile API: The following changes to the Messenger Platform's User Profile API have been announced:

    • Default profile fields: By default, the API will only return name, first_name, last_name, and profile_pic fields.
    • App-level extended profile field permissions: To access additional user profile fields, app developers must apply for each field in the Messenger Platform tab of the app console. For more information, see User Profile API - Available Profile Fields.
    • Deprecated fields: The last_ad_referral and is_payment_enabled fields are now deprecated, and will be removed from the API on October 30, 2018.

For apps created before the release of Graph API v3.1 on July 26, 2018, these changes will go into effect on January 8, 2019. Apps must be resubmitted and be approved for extended profile fields before this date.

For apps created after the release of Graph API v3.1 on July 26, 2018, these changes are in effect immediately.

June 29, 2018

  • Message ID Format: The format of the message ID returned in the message_id property of responses from the Send API has been changed.

May 30, 2018

  • App Submission Process: New app submissions are now required to be set to 'development' mode prior to submission.

May 23, 2018

May 22, 2018

May 11, 2018

Messenger Platform 2.4

  • The Customer Chat SDK is now included in the Facebook JavaScript SDK, and enables programmatic control of customer chat plugin features, such as hiding/showing the plugin, hiding/showing the greeting dialog and more.
  • The customer chat plugin now supports sender actions, user data quick replies, and enables users to send attachments.
  • Broadcast API introduces advanced targeting with label predicates, and enables easier broadcast management with scheduling.
  • Send to Messenger plugin now offers 20+ pre-defined strings to display as the plugin's button text.
  • Handover protocol makes it easier to manage thread state with the Thread Owner API, which returns the ID of the app that currently has thread control.
  • Messaging Insights API adds the page_messages_total_messaging_connections metric. This replaces the page_messages_open_conversations_unique metric, which is now deprecated.
  • Send API will automatically append default values for message sends that do not include the messaging_type property. Developers should continue to implement messaging_type as soon as possible.

May 1, 2018

April 4, 2018

  • Customer Matching via the Send API is now in closed beta, and is no longer accepting applications for new Pages. Pages that have previously been approved to use customer matching via the Send API and the Customer Matching API may continue to use the feature.

March 19, 2018

  • Customer chat plugin (beta) now supports the greeting_dialog_display and greeting_dialog_delay attributes. The minimized attribute is now deprecated; developers should migrate to using greeting_dialog_display as soon as possible.

February 26, 2018

Messenger Platform 2.3

  • Email and phone number quick replies now enable a simple way to ask the user to provide their email or phone number. The content of the quick replies are auto-populated from the user's Facebook profile. If the person has more than one email or phone number associated with their account, a separate quick reply will be shown for each.

  • Customer chat plugin (beta) introduces additional enhancements that will roll out this week, including an easy setup tool, in-browser notifications, and persistent menu support.

  • Messaging Insights API is updated with two new metrics: open conversations, and new conversations.

  • Page Inbox support for request thread control is now included in the handover protocol. Moving the conversation from 'Done' to 'Inbox' now automatically triggers a messaging_handovers webhook event.

  • Message Tags are updated for three new use cases based on your recommendations: COMMUNITY_ALERT, CONFIRMED_EVENT_REMINDER, NON_PROMOTIONAL_SUBSCRIPTION.

  • Checkbox Plugin now supports customization, including light and dark themes, a transparent background, and center alignment of the plugin content.

  • Broadcast API is officially released from beta. Thanks to all the great developers that implemented and gave us feedback!

Upcoming Breaking Changes

  • Page-level Subscription Messaging: Access to send subscription messages must now be applied for at the Page-level. Bots may continue to send subscription messages with the app-level permission until Dec 31, 2018, but Page admins that wish to continue sending subscription messages should apply for the new Page-level access as soon as possible. Page admins may apply for subscription messaging in the Messenger Platform tab of their Page settings.

  • NON_PROMOTIONAL_SUBSCRIPTION message tag: Pages that send subscription messages, are now asked to implement NON_PROMOTIONAL_SUBSCRIPTION as a message tag, rather than a messaging type. Beginning May 7, 2018, all Pages must include this message tag to flag all messages sent under subscription messaging policy.

February 13, 2018

February 1, 2018

  • Customer chat plugin (beta): Customization of the following is now supported in the Customer chat plugin: logged in greeting, logged out greeting, theme color.

December 5, 2017

  • Share to Messenger: The Facebook Sharing SDK has been updated to support sharing from native iOS and Android apps directly into Messenger conversations.

November 22, 2017

November 20, 2017

  • Send API: The character limit for text messages has been increased from 640 to 2000.

Breaking Change Notice

Beginning February 19, 2018, the following breaking changes will go into effect for the checkbox plugin and customer matching via the Send API.

  • Send API requests that use user_ref from the checkbox plugin or phone_number from customer matching to identify the message recipient will no longer trigger delivery of message_reads, message_deliveries, or message_echoes events to your webhook.

  • Send API requests that use user_ref from the checkbox plugin or phone_number from customer matching to identify the message recipient, the Send API will no longer include the recipient_id property in the API response.

November 7, 2017

Messenger Platform v2.2

  • Broadcast API is an open beta release that allows bots with the pages_messaging_subscriptions permission to send subscription messages to a multiple recipients with one API call. Messages can be sent to all open conversations or a set of PSIDs by using custom labels. You can also estimate the reach of a broadcast before it is sent and get the actual reach after the send takes place.

  • Customer chat plugin (beta) is a closed beta release that lets you add a Messenger chat window to your website. New users can start a conversation with your bot, and returning users will see recent chat history. The plugin is also optimized for the mobile web.

  • Media template is a new structured message template for sending images and video. The template supports sending images, videos, and animated gifs using an attachment_id, or the Facebook URL for any media that you have uploaded to Facebook, which means no more limits on the length of videos. The media template also supports adding an optional button.

  • Sending sponsored messages can now be done via the Messenger Platform with a single API request to the /sponsored_message_ads endpoint. This API is a thin wrapper that accepts a reduced number of properties, then calls the existing Marketing API on your behalf. Access to the API is already available to many developers, and will roll out to 100% over the next month.

  • Page-level feedback is a new addition to your Page settings, available under the 'Messenger Reviews' tab, that offers page-level aggregation of ratings and reviews. Before Platform v2.2, user feedback was only aggregated at an app-level.

  • Handover protocol is officially out of beta, and includes support for passing thread control to both the current and previous version of the page inbox. Rollout of support for the previous version of the inbox is expected to be available to 100% by mid-November.

  • Messaging Insights API now includes additional metrics: page_messages_blocked_conversations_unique, page_messages_reported_conversations_unique, and page_messages_reported_conversations_by_report_type_unique. These metrics replace page_messages_feedback_by_action_unique, which is now deprecated and will be removed in Graph API v2.12.

  • Built-in NLP now supports 11 languages for the default model, as well as default localization of date/time entities, and additional advanced settings.

  • Message tags for non-promotional use cases that require messages to be sent outside the 24-hour standard messaging window now include PAIRING_UPDATE and APPLICATION_UPDATE.

Upcoming Breaking Changes

  • messaging_type property should be included in the body of the request for all message sends, as of this release. Beginning May 7, 2018 the messaging_type property will be mandatory and all messages sent without it will not be delivered. For more information, see Sending Messages - Messaging Types.

  • page_messages_feedback_by_action_unique metric in the Messaging Insights API is now deprecated and will be removed in Graph API v2.12. For more information, see Analytics.

August 31, 2017

3 New Message Tags

Three new message tags are available for sending non-promotional messages outside the 24-hour standard messaging window:

  • ACCOUNT UPDATE: Used to confirm updates to a user's account setting. For example, when there is a change in account settings and preferences of a user profile, notification of a password change, or membership expiration.
  • PAYMENT_UPDATE: Used to provide payment updates to existing transactions. For example, it can be used to send a receipt, out-of-stock, auction ended, refund, or a status change in an existing purchase transaction.
  • PERSONAL_FINANCE_UPDATE: Used to confirm a user's financial activity. For example, it can be used to send notifications on bill pay reminders, scheduled payments, receipts of payment, transfer of funds, or other transactional activities in financial services.

For complete details, see Message Tags.

July 27, 2017

Messenger Platform v2.1

  • Built-in NLP is a simple way for developers to incorporate natural language processing into their bots. Built-in NLP automatically detects meaning and information in the text of messages, before it gets passed to the bot.

  • Handover protocol enables cross app collaboration within a single Messenger experience. The handover protocol enables businesses to create multiple experiences within a single bot.

  • Enhancements:

    • The new SDK for payments makes the Messenger webview payment process easier and more efficient. Customers can now pay using a one-step process through Messenger webview. The webview payments SDK for Messenger Platform v1.2 - 2.0 is now deprecated - support will continue for these versions through February 1, 2018.
    • Added expanded set of Facebook Page buttons: Shop Now, Get Support, Get Updates, Play Now and Get Started.
    • Added desktop support for Messenger Extensions SDK that extends functionality across mobile and web. This allows features like user ID and sharing to be available on desktop.
    • Updated customer matching API allows matching prior to sending a message to a phone number, and optionally a name, via the API.
    • Added Chat Extensions for Global Pages. Enables thread sharing across regions using the webview and Chat Extension.
    • Added policy enforcement notifications, which send notifications when a bot has been blocked or policy issues arise.
    • Added new messaging tags to make it easier to respond to customers’ questions and provide updates: APPOINTMENT_UPDATE, GAME_EVENT, TRANSPORTATION_UPDATE, FEATURE_FUNCTIONALITY_UPDATE, TICKET_UPDATE.

April 18, 2017

Messenger Platform v2.0

  • Discover tab added to Messenger, showcasing popular bots in our ecosystem, nearby places that people can message, and businesses that offer support or answer questions.

  • Chat Extensions lets bots build interactive, social features that users can invoke directly into their conversations via the composer.

  • Parametric Messenger Codes let a bot dynamically generate multiple Messenger codes that provide different functionality when they are scanned. Users can also now scan codes by holding down on the main camera interface in Messenger.

  • Enhancements:

    • The ID Matching API enables the pairing of ASIDs and PSIDs between an app and a bot belonging to the same business

    • Open Graph Template lets bots send open graph content directly to threads. Currently supports only music URLs natively with inline playback.

    • Bots can now access referral information when users enter via a Messenger Ads.

    • Released the Platform Design Kit, a library of components for designing bots.

April 5th, 2017

March 2nd, 2017

Messenger Platform v1.4

November 8th, 2016

Messenger Platform v1.3

September 12th, 2016

Messenger Platform v1.2


  • Messenger Destination Ads are now available under the website clicks objective - that means you can acquire users directly into your bot with no friction
  • Export your bot analytics on the app level to see block rates and open threads for all your pages.
  • New welcome screen when people first enter a conversation with your bot

August 30th, 2016

August 15th, 2016

  • Added a new doc: Messenger Platform Policy Overview. Please review as policy changes may impact your integration.
  • Re-added the Complete Guide which has now been broken up into multiple sections.
  • Doc navigation changes.

July 1st, 2016

Send API

Receive API

  • New event: message_echoes. Allows developers to receive all messages sent by pages.
  • New event: message_reads. To notify the developer/page a message was read.
  • New field: app_id, to identify the source of the bot message.
  • New field: metadata, passed from the Send API and sent to the message_echoes callback, to help interoperability betwen multiple bots.

User experience

  • Breaking change: Get Started button. Triggers a postback received callback instead of firing a message automatically.
  • New input style: Quick replies. A new way for bots to receive input with ephemeral buttons attached to the last message
  • New button type: Phone number to invoke the native phone dialer
  • New thread setting: Persistent menu. Supports postbacks and urls with up to five elements
  • New thread setting: Greeting text. To communicate your bot's functionality to first-time users.
  • Browser close. To allow automatically closing the browser window at the end of a custom web UI flow.
  • Account linking and unlinking: secure protocol for businesses to retrieve a page scoped user ID from within Messenger
  • Bot feedback: Users are able to leave a 5-star review and provide feedback for developers.

April 12th, 2016

  • Messenger Platform launched.