The Messenger Platform follows Graph API Versioning.
Visit the Developer Settings guide to manage notifications for the Messenger Platform Changelog.
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.
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
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.
Messenger API for Instagram is now available for Instagram Creators account type with less than 500K followers. Please see details in the developer documentation.
https://ig.me/m/{ig_profile_handle}
on website, email, and more. Please refer to the developer documentation for more details.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.
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
).
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.
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.
The following changes take effect on v8.0+ today and will affect all versions on Aug 4th, 2022
The following changes take effect on v7.0+ today and will affect all versions on November 2nd, 2020
The following changes take effect on v7.0+ today and will affect all versions on May 5th, 2022
The following changes apply for v6.0+
messages
- Adjusted the way attachments type fallback
and image
with a sticker are sent.The following APIs are deprecated on v6.0+ and will be removed from all versions on June 30th, 2020
The following APIs are deprecated on v6.0+ and will be removed from all versions on May 4th, 2020
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
The following breaking change date is adjusted to June 30, 2020, the features described below remain deprecated.
read_page_mailboxes
used in Conversation API and Legacy Private Reply, deprecated in favor of the pages_messaging
permission.conversations
is deprecated. Please migrate to use the messages
webhook field supported in Messenger platform instead.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)
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).
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.
The following APIs are deprecated on v4.0+
The following APIs are deprecated on v4.0+ and will be removed from all versions on October 29th, 2019
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
Won't function with the new app
Will render differently in the new 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.
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.
The following breaking changes apply to version 3.3+ of the Graph API, and will apply to all lower versions on July 31st, 2019.
pages_messaging_subscriptions
permission has been deprecated.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).
pages_messaging
permission as we deprecate read_page_mailboxes
on April 30th, 2019. For apps previously approved with read_page_mailboxes
but not pages_messaging
, we encourage developers to apply for the permission as soon as possible to avoid any service disruption.conversations
is deprecated. Please migrate to use other webhook fields supported in Messenger platform instead.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.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.User Profile API: The following changes to the Messenger Platform's User Profile API have been announced:
name
, first_name
, last_name
, and profile_pic
fields. 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.
message_id
property of responses from the Send API has been changed.sentiment
entity to default NLP.page_messages_total_messaging_connections
metric. This replaces the page_messages_open_conversations_unique
metric, which is now deprecated.messaging_type
property. Developers should continue to implement messaging_type
as soon as possible.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.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!
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.
/request_thread_control
endpoint that allows secondary receiver apps to request thread control from the primary receiver app.ISSUE_RESOLUTION
tag. whitelisted_domains
updated to accept a maximum of 50 domains. Previously the maximum was 10.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.
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
.
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.
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.
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:
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.
Also: