Messenger Platform

Messenger Platform Changelog

The Messenger Platform follows Graph API Versioning.

Visit the Developer Settings guide to manage notifications for the Messenger Platform Changelog.

April 19, 2022

  • Ice Breakers on Messenger API now supports localization allowing businesses to set custom ice breakers depending on the user locale. The API will have a new format and we encourage developers to leverage the new format to set and retrieve Ice Breakers information.
  • Messenger apps which haven’t completed business verification must complete verification by July 19th, 2022. If apps don’t complete business verification by then, they won’t be able to send and receive messages via Messenger and pages_messaging permission for these apps will be revoked. Developer alerts have been sent to the impacted apps. If you have already completed business verification for your Messenger app no further action is needed.
  • We have restored message reads, deliveries and reactions webhooks on Messenger Platform that weren’t available to businesses in Europe, and for people in Europe & Japan who connect with businesses globally.

March 15, 2022

We have launched the Persistent Menu for Messenger API support for Instagram. This enables users to discover and interact with a Page’s main features.

Mar 14th, 2022

As per the announcement on September 14th, 2021, all Facebook pages will now be migrated to support the new Handover Protocol behavior. We expect to have all Pages migrated by March 18th, 2022. Please refer to the breaking changes section for more details. Here’s a summary of key improvements that were announced previously.

We are making improvements to Handover Protocol which helps developers and businesses launch messaging experiences (i.e. apps) quickly, makes it easy to pass control of conversation between apps and ensures a great user experience by disallowing apps from interjecting ongoing conversations. Key improvements include Exclusive mode, Idle mode, New APIs for finer control over thread ownership and removing the requirement to assign primary or secondary roles for apps

Feb 7th, 2022

We have launched the Chat Plugin Entrypoint customization settings through API as well as our first party setup tool. This will provide businesses with the option to choose the entry point icon and its label from a set of presets that best fits their branding. For more details please see our developer documentation.

Nov 11th, 2021

Messenger API for Instagram is now available for Instagram Creators account type with less than 500K followers. Please see details in the developer documentation.

Nov 9th, 2021

Oct 20, 2021

Messenger Platform Announcement

  • IG comments webhook and API are updated with additional fields. Please refer to the developer documentation for more details on new fields.
  • Starting support for IG.me link, a shortened URL service that directs users to messaging experience on Instagram. Developers can use the link format https://ig.me/m/{ig_profile_handle} on website, email, and more. Please refer to the developer documentation for more details.
  • We have made updates to the Ice Breaker on Instagram to support multiple versions in different languages. Developers can now set up Ice Breakers in different languages and serve the right version to users based on user locale. Please refer to the developer documentation for more details.

Sept 14, 2021

Messenger Platform Announcement

  • Handover Protocol Improvements

  • Custom Labels API - We are making exciting updates to the Custom Labels API that would allow businesses to create, update and delete labels and sync the labels between the Facebook Page Inbox and any other tool the business might be using to communicate with their customers.

    1. In order to use the Custom Labels API after October 1st, 2021 businesses need to accept our new Page Contact Terms. These terms describe Meta’s data practices for the Custom Labels created by the business. We will be rolling out the Page Contact Terms acceptance requirement to Facebook Pages on a rolling basis starting October 1st.
    2. Graph API v12.0+ Custom Labels API name field will be replaced with page_label_name. This change will take effect on all older Graph API versions starting Dec 14th, 2021. Developer should leverage page_label_name across various CRUD (Create, Retrieve, Update, Delete) API calls and webhooks.

  • Messenger API Updates for Europe & Japan - We have restored Customer Feedback Template in the Messenger API that wasn’t available to businesses in Europe, and for people in Europe & Japan who connect with businesses globally. Details here.

  • Messenger API for Instagram updates

    • Reaction Webhook - We have updated emoji reactions to return a new unicode format and support multiple emoji reactions. Please refer to the developer documentation and migrate to the new version before December 14th, 2021 in order to continue supporting emoji reactions.

    • User Profile API - We have updated User Profile API to include additional fields that are publicly available on the Instagram app. Please refer to the developer documentation for details.

    • IGID Deprecation - Conversation API will no longer return IGID field and fully rely on IGSID field. See developer documentation for details in order to migrate before December 14th, 2021.

  • Facebook Chat Plugin Customization API - We are launching Chat Plugin customization settings through API. With this new release, developers will be able to edit features including the position, color, greetings, guest mode settings, etc. that are currently only available using our first-party tools today.

  • Message Echo webhook will now include the app id for Facebook Page Inbox as part of Graph API v12.0 - When a business responds to a Messenger conversation from Facebook Page Inbox, other apps connected to the Page can listen to the Message Echo webhook. These apps will receive an echo webhook with the Facebook Page inbox app id (263902037430900).

Aug 16th, 2021

Messenger Platform Announcement

  • Messenger API for Instagram- Messenger API for Instagram opened up to all developers in June, with an opportunity to build for IG business accounts with follower counts between 10k-100k. Now, developers can add Instagram messaging into their apps and build Instagram messaging experiences for all businesses on Instagram. The use of Messenger API for Instagram must comply with the Developer Policies, particularly the policies listed under ‘Messenger and Instagram Messaging APIs’, as well as the technical documentation.

Aug 10th, 2021

Messenger Platform Announcement

  • Messenger API Updates for Europe & Japan - We have restored many of the features in the Messenger API that weren’t available to businesses in Europe, and for people in Europe & Japan who connect with businesses globally. See the list of all restored features here.

Aug 6th, 2021

Messenger Platform Announcement

  • Private Replies on Instagram Messaging API no longer need to be sent using the Human Agent Message Tag. Private Reply API calls with the Human Agent Tag will stop working after Sept 13th, 2021.

Aug 4th, 2021

Messenger Platform Announcement

  • Update on Messaging Referrals Webhook - We added the product_id inside ads_context_data block in the messaging_referrals webhook to allow apps to get the product ID if it is a dynamic ads.

Jul 7th, 2021

Messenger Platform Announcement

  • Messenger API for Instagram - Messenger API for Instagram opened up to all developers in June, with an opportunity to build for IG business accounts with follower counts between 10k-100k. We are expanding the rollout to IG business accounts with follower counts between 1K-10K. Now, developers can add Instagram messaging into their apps and build Instagram messaging experiences for even more businesses. The use of Messenger API for Instagram must comply with the Developer Policies, particularly the policies listed under ‘Messenger and Instagram Messaging APIs’, as well as the technical documentation.

June 22th, 2021

Messenger Platform Announcement

  • Generic Templates, which allows you to send a structured message that includes an image, text and buttons, is now available for Instagram

June 8th, 2021

Messenger Platform Announcement - Graph API V11.0

The following changes apply to v11.0+

  • Adding <mid> to messaging_postback events for Messenger & Messenger API for Instagram for Graph API V11.0+ - We are adding the Message Id (<mid>) field as part of the messaging_postback payload to help reduce engineering overheads for our partners who have had to rely on the Conversations API to fetch conversation history and then compare it with the webhook events. See more details here.

  • Airline Templates are deprecated - Airline Templates will no longer be supported starting Graph API v11. Deprecation for the prior versions of the Graph API will occur 6 months after the announcement of this change on Dec 6th, 2021. We recommend airlines send Boarding Pass and Check-in templates as images which are consistent with how they typically send these notifications in other channels.

June 2nd, 2021

Messenger Platform Announcement

  • Messenger API for Instagram - We have opened up the Messenger API for Instagram to all developers who are making it possible for brands to offer messaging experiences on Instagram at scale. Now, developers can add Instagram messaging into their apps and build experiences for Instagram messaging. Developers can help businesses use different applications to leverage existing workflows, drive more meaningful conversations, increase customer satisfaction, and grow sales. Learn more here. The use of Messenger API for Instagram must comply with the Developer Policies, particularly the policies listed under ‘Messenger and Instagram Messaging APIs’, as well as the technical documentation.

  • Human Agent message tag now available to all developers - This tag allows businesses to respond to user messages on Messenger & Instagram manually outside the 24-hour standard messaging window up to 7days. This tag is helpful especially for use cases such as weekend closures or for inquiries that need more than 24 hours to resolve. Developers should apply for the Human Agent tag permission via the App dashboard even if your app has been previously approved for Human Agent message tag. Navigate to the “Permissions and Features” section of the app dashboard and apply for the “Human Agent” permission. Learn more here.

  • Customer Feedback Template is now available as Beta - We are launching a native template within Messenger that supports common survey formats such as CSAT (Customer Satisfaction), NPS (Net Promoter Score), CES (Customer Effort Score) and free form text. The native template is easier to integrate because it’s built on Send API, eliminates the need to build custom survey solutions using Webview and makes it easy for developers to aggregate scores across channels that use similar survey formats. Learn more here.

Apr 13, 2021

Messenger Platform Announcement

  • Messenger API Updates for Europe & Japan - We have restored many of the features in the Messenger API that weren’t available to businesses in Europe & Japan, and for people in Europe & Japan who connect with businesses globally. See the list of all restored features here.

Mar 30, 2021

Messenger Platform Announcement

  • Messenger API Updates for Japan - As part of our ongoing efforts to comply with regulations under the Japan Telecom Business act, several Messenger APIs will be unavailable for developers and businesses in Japan, and for people in Japan who connect with businesses globally. These Messenger API changes are similar to the changes we announced for Europe back in December.

Dec 15, 2020

Messenger Platform Announcement

Dec 01, 2020

Messenger Platform Announcement

  • Messenger API Updates for Europe - As part of our efforts to comply with new privacy rules in Europe, we're making updates that will impact some developers and businesses that use our Messenger API. Beginning December 16th, several Messenger APIs will be unavailable for developers and businesses in Europe, and for people in Europe who connect with businesses globally.

Aug 04, 2020

Messenger Platform Announcement - Graph API V8.0

  • Introducing updates to the Facebook Chat Plugin (formerly known as the Customer Chat Plugin) – Today, we are introducing a new and improved design, and the Chat Plugin now connects businesses to all users on their websites, even if they are not logged into Facebook. To ensure optimal user experience, we recommend that developers read the new webhooks that detect if a user is messaging the business in guest mode, and when the guest session is terminated.
  • Shops API - We are launching support for sending and receiving products on Messenger for Shops. This includes the Product Template that can be used to send products in messages, product details page (PDP) referral info in message webhook, Product XMA support in Conversation API, webhooks for messages with product template and messages from Facebook Shops Product Detail Page, and echo webhooks for messages with products.
  • App Review Submission Changes - We have merged the Messenger app review process with the main app review and provided instructions in a sample submission.

The following changes take effect on v8.0+ today and will affect all versions on Aug 4th, 2022

  • Nested Persistent Menu - Messenger Profile API and Customer User Settings API will not support nested menus on v8.0 and above. Additionally, these APIs will allow creating flat (single level) menus with up to 20 items. The latest Android app will flatten nested menus, just as the iOS app does.
  • Thread Settings API - Thread Settings API was replaced by Messenger Profile API in 2017. It will not be available on v8.0 and above.

May 05, 2020

Messenger Platform Announcement - Graph API V7.0

The following changes take effect on v7.0+ today and will affect all versions on November 2nd, 2020

  • Customer Chat Plugin Webhooks - When a new conversation is started or an existing conversation continued via the Customer Chat Plugin, the webhook events messaging_postbacks and messaging_referrals will include a user_ref instead of PSID until the user sends a message.

The following changes take effect on v7.0+ today and will affect all versions on May 5th, 2022

March 04, 2020

Messenger Platform Announcement

  • Introducing Messenger Webhook Versioning - Allowing a window for developers to opt-in into platform changes affecting webhooks. Version changes can be done live and rolled back if needed to promote smooth migrations.
  • Update on Share to Messenger SDK - Last June, we announced plans to no longer support the Share to Messenger SDK. We are excited to share that we will continue to support a modified version of the Share to Messenger SDK, which will allow people to share links and photos from your app to Messenger. The support for link and image/video sharing on the iOS Messenger app will be rolled out gradually over the next few weeks. We will no longer support sharing generic and media templates. If you still have the SDK in your app, no action is required.
  • Policy Enforcement - The updated Messenger Platform Policy is in effect starting today.

The following changes apply for v6.0+

February 04, 2020

Messenger Platform Announcement - Graph API V6.0

  • One Time Notification API (beta) - As promised in our Dec 20th announcement, we are rolling out the beta for One Time Notification API today. This will allow Users to give Pages the permission to send a future notification message outside of the 24 hour response window.

The following APIs are deprecated on v6.0+ and will be removed from all versions on June 30th, 2020

  • Sending Messages through Conversation API - This legacy endpoint is being deprecated in favor of the more feature rich Send API. Developers have until June 30th, 2020 to update their apps before this functionality breaks on all versions of the API.

The following APIs are deprecated on v6.0+ and will be removed from all versions on May 4th, 2020

  • Page Message Tags API - As we have simplified and reduced the number of our message tags, it is recommended to hard code them in your app.
  • User Threads API - Note that this reference page is available only to apps on v4.0 or before.

December 20, 2019

Messenger Platform Announcement

Today, we are sharing a new effective date for the policy changes that we announced on August 29, 2019 to give developers and businesses additional time to prepare for the policies and incorporate new messaging features. The new policy will now go into effect on March 4, 2020. For more details, see the Messenger Platform Policy Overview

The breaking change announced on October 29, 2019 affecting Broadcast API and Legacy sponsored messages has been set for March 4, 2020.

Based off feedback from our community, we identified additional use cases aligned with our policy principles that were not covered under the original set of message tags. Thus, we are planning to introduce a “one-time notification” API in February.

For more details, see Listening to our Community: Messenger Provides More Time to Adapt to New Policies and Announces One-time Notification API

December 04, 2019

Messenger Platform Announcement

  • User Level Persistent Menu - We are making it easier for businesses and developers to personalize conversational experiences at the user level on Messenger. Taking this feature out of closed beta into general availability.
  • Helper Webhooks for user reactions and message replies - We added a temporary toggle that allows apps created before this date to opt in into human readable descriptions of replies and reactions to help apps show them to agents without code changes.

The following breaking change date is adjusted to June 30, 2020, the features described below remain deprecated.

October 29, 2019

Messenger Platform Announcement - Graph API V5.0

  • Handover protocol improvements for click to Messenger ads - We are making it easier for businesses that have multiple apps connected to the Messenger platform to dynamically select the app that they want to use for their click to Messenger ads.
  • Ice Breakers - Ice Breakers help businesses reduce friction in starting a conversation by surfacing common questions or topics of interest. Businesses can now set icebreakers on their Messenger profile via the API.
  • Webhooks for user reactions and message replies - It is now possible to receive webhook events when users react or reply to messages from businesses.
  • Filter for admin text - Admin texts are messages sent by Messenger during conversations between people and businesses. We are now adding a filter to the thread API to allow apps to request messages without them.

The following APIs are deprecated on v5.0+

The following APIs are deprecated on v5.0+ and will be removed from all versions on March 4, 2020 (Updated on December 20, 2019)

September 30, 2019

Messenger Platform Announcement

  • User Level Persistent Menu - We are making easier for businesses and developers to personalize the conversational experience at the user level on Messenger. With this beta, apps will be able to dynamically change the persistent menu and the visibility of the composer.
  • Private Replies - We made improvements to private replies. The old Private Replies only allowed plain text to be sent. With this update businesses can send images, templates and quick replies as part of the message they send in response to a post or comment on their Page.
  • URL Buttons have App Link Support - We are improving the mobile integration capabilities in Messenger by introducing App Link support for URL buttons. This will allow developers and businesses to provide a button that can click into a native app.
  • Changelog Notifications - Developers can now subscribe to email notifications of changes in this changelog.

August 29, 2019

Messenger Platform Announcement - Policy Update

The Messenger Platform’s policies are designed to help people and businesses connect in ways that drive meaningful outcomes. At the heart of this is the understanding that people and businesses need a seamless, reliable way to get something done - whether it is getting a question answered, making a purchase, or communicating important and relevant updates. The following policy update is designed to make communication between people and businesses on Messenger relevant, important and timely.

Apps have until March 4, 2020 (Updated on December 20, 2019) to migrate to the new policy. We highly encouraged developers to adopt these policies right away to ensure a smooth transition. See Messenger Platform Policy Overview

Effective March 4, 2020 (Updated on December 20, 2019).

  • Revised Standard Messaging Window Policy: We are updating our policies to a 24-hour standard messaging window. We know that people expect businesses to respond quickly and, not surprisingly, businesses that respond in a timely manner to achieve better business outcomes. To improve the people to business experience, businesses will no longer be able to send a message outside the 24-hour window as part of the standard messaging window policy.
  • Introducing More Streamlined Message Tags: We are simplifying message tags. Message tags enable businesses to send personalized, 1:1 messages to people outside of the standard messaging window. Message tags are now available for the following use cases: post-purchase updates, event reminders, and account updates, and human agent (closed beta).
  • Effective Audience Reengagement Outside 24-Hour Message Window: Businesses who want to send one message to many people, which may include promotional content, outside the standard messaging window, have the opportunity to use sponsored messages. Sponsored messages are a great way for businesses to re-engage people who currently have an open chat with the business.
  • Subscription Messaging Beta Update: We are updating this policy as we found some businesses were using the subscription messaging beta in ways that weren’t in line with our policy and led to a poor experience for people and other businesses. Moving forward, subscription messaging will only be available for news organizations who successfully register their Pages through the Facebook News Page Index to help improve the user experience and business outcomes.

For more details, see the Messenger Platform Policy Overview

Discovering Businesses on Messenger As a part of our continued commitment to simplify the Messenger experience for people, we are removing the Discover tab from the Messenger app. We will continue to invest in more and better ways to help businesses connect with their customers wherever they are, including updates to m.me links, various entry points across our family of apps, as well as ad products that lead to Messenger.

July 29, 2019

Messenger Platform Announcement - Graph API V4.0

  • M.me links now reopen the 24hr window within existing threads. When a person clicks an m.me link that contains a ref parameter and is taken into an existing thread, it will now reopen the 24hr standard messaging window. This will allow apps powering Pages to reply to people based on the context that the ref parameter provides.
  • Messenger rate limit - The new rate limit is now tied to the number of people a Page can send messages to. Enforced on v4.0+ and will apply to all versions on October 29th, 2019.

The following APIs are deprecated on v4.0+

Breaking Changes

The following APIs are deprecated on v4.0+ and will be removed from all versions on October 29th, 2019

June 10, 2019

Messenger Platform Announcement

During F8 2019, we announced our plans to launch a lighter, better and simpler Messenger designed to build closer connections between people and businesses. Starting August 15, 2019, updated versions of the Messenger app will reflect the following changes:

Won't render on the new app

  • Location quick reply which allows people to send their location in the Messenger thread will no longer be rendered. We recommend businesses ask for zip code and address information within the thread. While we are sunsetting the existing version of Share Location, in the coming months we will be introducing new ways for people to communicate their location to businesses in more valuable ways.
  • Share Button within the media, list and generic templates will no longer render. People can use the Messenger forward functionality instead of the Share Button.

Won't function with the new app

  • Begin share flow Messenger extension SDK that allows developers and businesses to trigger a share experience from a webpage that loads within Messenger . As a workaround, developers can generate a link using the context in the webview and provide a way for user to copy the link and share it in the Messenger conversation.
  • Share to Messenger SDK that allows people to share links and media from apps to Messenger will no longer be supported. Businesses and developers might need to make modifications to their app to trigger native OS sharing. People will be able to share content to Messenger using the native sharing features that is built into their devices.
  • Messenger Codes the Messenger camera will no longer support scanning these codes. We believe this experience will be more seamless by leveraging the phone's native capabilities to scan QR codes with m.me links.

Will render differently in the new app

  • Vertical list templates will no longer be supported. Instead, we recommend businesses use the horizontal scrollable carousel template. Vertical list templates will render as horizontal scrollable carousel template post August 15th.
  • Nested menu will no longer be supported. To create a more seamless experience for people on Messenger, we are transitioning from nested persistent menu to a single layer menu format. We believe this will create an even better experience for people on Messenger. Nested menu items will render as a flat list.
  • Open Graph template which allows people to play songs inline within Messenger will no longer be supported. As a fallback, we are rendering the generic template which links to the URL. When a user clicks on the song that is shared in Messenger, the user will be directed to the audio streaming platform's website or app.

Messenger Bot Reviews will be removed on August 15, 2019. They allowed people to leave a star rating and review for a bot. Page owners will no longer be able to view these ratings for their app and Page in the Page Settings or in App Dashboard.

May 08, 2019

Breaking Change Notice

Effective as of today, the parameter seq will always be 0 for all Messenger webhook events. This deprecation was announced on November 8, 2016. After Jul 31, 2019 the seq parameter will no longer be included in webhook events. To de-duplicate messages use the mid parameter.

April 30, 2019

Messenger Platform Announcement - Graph API V3.3

  • We are introducing a new Page control to allow a Page admin opt into a Page messaging rate limit to prevent the Page from being transitioned into a high-MPS Page.
  • We are introducing a new sample Messenger App, Original Coast Clothing, to showcase Messenger automation features. This demo includes a how-to guide and open-source code to deploy on your server.

Breaking Changes

The following breaking changes apply to version 3.3+ of the Graph API, and will apply to all lower versions on July 31st, 2019.

  • The Broadcast API will support the Page-level subscription feature only, as the app-level pages_messaging_subscriptions permission has been deprecated.
  • The Messaging Insights API will remove 2 outdated metrics: page_messages_active_threads_unique and page_messages_reported_conversations_by_report_type_unique.

The following breaking changes apply to version 3.3+ of the Graph API, and will apply to all lower versions on June 30, 2020 (Updated on December 4, 2019).

January 8, 2019

Breaking Change Notice

  • User Profile API: We previously updated default access for the User Profile API to only include name, first_name, last_name, and profile_pic. Effective as of today, all apps shall have access to additional profile fields if they have been approved in app review. You may apply for access to additional fields in the Messenger Platform tab of your app console.
  • Customer chat plugin (beta): Starting today, you will need to use sdk/xfbml.customerchat.js library in order to render the customer chat plugin on your website. You'll no longer be able to use sdk.js to load the plugin.
  • Checkbox Plugin: Following the default state of the checkbox plugin being unchecked, as of April 9, 2019, we will no longer allow a pre-checked state.

December 4, 2018

Updates

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

Also:

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