Messenger Platform

Messenger Platform Changelog

This document contains the changelog for current versions of the Messenger Platform. The Messenger Platform follows Graph API Versioning.

The latest version is: v19.0

Related Changelogs

April 9, 2024

message_edits Webhook Event

The new message_edits webhook event notifies you when a user edits a previously-sent message. Learn more about this webhook event here.

March 12, 2024

Welcome Message Flows

Welcome Message flows can now be configured for messaging ads using the marketing API. Learn more about Click to Messenger ads here and Click to Instagram ads here.

February 20, 2024

Messaging Webhooks for Messenger

"Reel" will now be a supported attachment type for message webhooks sent for Messenger conversations. Reel attachments will be categorized as type reel and the attachment payload will include the title, URL, and video ID of the reel.

January 10th, 2024

Commands

Commands are tappable keywords that the user can invoke at any time to perform specific actions within the Messenger experience. Commands are composed of the command itself and a hint, which educates the user on what it does. For example, when a user types "help me book flights and hotels to Mexico for the last week of december," they are invoking the flights and hotels commands configured by the travel business. Learn more here.

Commands menu

The commands menu is a new menu that we are introducing that will automatically appear when you set up commands. If you already have a persistent menu set for your Messenger experience, the commands menu will override it. Learn more here.

Share sheet

People can now share your messaging experience from the business profile page on Messenger. This helps drive word-of-mouth discovery of your Messenger experience. Learn more here.

Business profile updates

Commands will appear on the business profile once you configure the commands for your Messenger experience. People can navigate to the business profile by tapping on the page name at the top and learn about the commands you have made available in your Messenger experience.

Welcome screen update

The welcome screen shows the list of commands supported by the messaging experience, making it easy for people to understand what actions the Messenger experience can perform. Learn more here.

Messenger app review update

If you are developing the app to send and receive messages for your own page, you will not have to go through app review. Note that if you are planning to fetch user profile information, you still need to go through app review for the permissions required for accessing the User Profile API.

October 17, 2023

Conversation Routing for Instagram

Conversation Routing is now available for Instagram. Conversation Routing allows Meta to route conversations between your business and customers, or prospective customers, to the app that you have specified to respond in the conversation. This routing allows your business to create rich conversations with people and to minimize API calls to Meta's servers.

Custom Labels and Personas APIs

The Custom Labels API and Personas API access has been restored to businesses that operate in Europe, and for people in Europe and Japan who connect with businesses globally.

Updates to welcome message flows for Ads that Click to Messenger and Instagram Direct

Businesses and agencies can now easily connect their Click to Messenger and Click to Instagram Direct ads to a welcome message created in a partner app without having to use a JSON code snippet. The welcome message will appear as a dropdown in ads manager when creating the Click to Messenger and Click to Instagram Direct ad. Learn more about it here.

October 12, 2023

Private Replies

Private Reply is now available for comments on Facebook Reels.

September 20, 2023

Private Replies

Updates to Private Replies for groups, new fields supporting commenter information via from field and parent context via parent_id introduced to the group_feed webhook. You may need to update your webhooks server to handle these new fields.

September 12, 2023

Conversation Routing

As a business, you may use multiple third-party messaging providers for different conversations with your customers, like lead generation, marketing offers about your products, or customer support questions. Conversation routing lets you define which partners control customer conversations at a particular time, so that customers get the information they need. You can create and manage message routing rules in your Page settings.

Button Template for Instagram

The button template sends a text message with up to three attached buttons. This template is useful for offering the message recipient options to choose from, such as predetermined responses to a question, or actions to take. Supported button types are postback and web_url.

September 12, 2023

Conversation Routing

As a business, you may use multiple third-party messaging providers for different conversations with your customers, like lead generation, marketing offers about your products, or customer support questions. Conversation routing lets you define which partners control customer conversations at a particular time, so that customers get the information they need. You can create and manage message routing rules in your Page settings.

Button Template for Instagram

The button template sends a text message with up to three attached buttons. This template is useful for offering the message recipient options to choose from, such as predetermined responses to a question, or actions to take. Supported button types are postback and web_url.

July 26, 2023

Lead Ads for Messenger

  • Instant Form Message Template

June 30, 2023

Lead Ads for Messenger

  • Lead form ads in a Messenger conversation
  • Booking Button

June 20, 2023

Instagram Messaging with the Messenger Platform

Instagram Messaging is now available for any Instagram Professional account for a business or a Creator.

June 15, 2023

Ads that Click to Messenger

Call Prompt

You can now add a call prompt to allow customers or people interested in your business to call your business.

Click to Subscribe

You can now create ads that include a click to subscribe flow that allow you to ask customers or people interested in your business to opt in to receiving marketing messages.

Multi App Routing

Multi App Routing is now available for Instagram Direct and Messenger.

May 10, 2023

Private Replies

Your business can now send Private Replies to a person who commented on a Facebook Group Post.

Recurring Notifications

Recurring Notifications is now known as Marketing Messages.

Templates

A Structured Template is now available to gather shipping information from a customer.

April 25, 2023

Messaging Insights API

New metrics and parameters are available for the Messaging Insights API.

February 21, 2023

Recurring Notifications for Messenger Platform

Titles for Opt In Request

The title property for recurring notification opt in requests is no longer required. If title is not set, the value defaults to "Updates and promotions". This change applies to opt in requests sent from a Facebook Page or Instagram Professional accounts.

February 2, 2023

Recurring Notifications for Messenger Platform

Message Frequency for Opt In Requests

The notification_messages_frequency property for recurring notification opt in requests is deprecated and will no longer be returned in GET requests or webhook notifications. However, notification message tokens created before Feb. 2, 2023 for weekly or monthly recurring notifications will be supported and the notification_message_frequency will be returned in webhook notifications.

Followup Messages for Opt Ins

You can now send up to three followup messages to a person who has opted in to receiving recurring notifications. All three followup messages must be sent within 2 minutes of the first followup message.

Notification Message Tokens

The GET /PAGE-ID/notification_message_tokens endpoint is now available for Instagram Messaging.

The next_eligible_time property for Notification Message Token endpoints is now available. This field returns the time at which you are able to send the next recurring notification using that notification message token.

Messenger API for Instagram

You can now send GIFs in messages sent from an Instagram Professional account using the Messenger API for Instagram.

The Attachment Upload API now supports uploading media for messages sent from an Instagram Professional account.

Referral information for ads that click to an Instagram conversation (CTD) is now returned in messages webhook notifications.

January 2, 2023

Messenger Platform Insights

Beginning March, 31, 2023, you will no longer be able to download a CVS file from the Messenger Analytics dashboard. Visit the Messaging Insights API to learn how to get these insights.

November 9, 2022

Business Login for Instagram

Business Login for Instagram makes it easier for you to onboard Instagram users who still need to configure their account for API access through modal pop ups and fewer steps.

Improvements between Click to Messenger, Lead Gen ads and Messenger Platform

We’ve made following up on Lead Gen ads that Click to Messenger easier through:

  • A new Referral Webhook for Click to Messenger, Lead Gen ads that include the lead information.
  • Improvements to the Handover Protocol. Advertisers can now select which app they want to route completed leads. Additionally, for apps that haven’t yet implemented these app notifications, an optional summary message can be enabled, to send lead information to that app in the form of a regular message.
  • Since referral or summary events are triggered while the standard messaging window is open, apps can use this to follow-up with leads directly in Messenger, upsell them to Recurring Notifications or have them book an appointment or call the business directly.

Messaging Events API

Messaging Events API supports the lead_submitted event. Businesses can use this event to report lead submissions from Click to Messenger ads. This new messaging event is released as an Open Beta. Reporting in Ads Manager will come soon.

Persistent Menu

Persistent Menu is now available for Instagram Messaging.

Private Replies

Instagram Messaging now supports Private Replies for comments on Instagram Live Stories and ads posts. You may need to update your webhooks server to handle these new fields.

Recurring Notifications

You can now get a list of all valid Notification Message Tokens using the GET /PAGE-ID/notification_message_tokens endpoint.

October 17, 2022

Recurring Notifications

App IDs will no longer be associated with notification message tokens. All apps linked to a Page will now receive opt in webhook notifications when a person has opted in to receive recurring notifications.

The following message attachment payload fields have been added:

  • image_aspect_ratio – Set an image to a horizontal or square aspect ratio for opt in requests
  • elements – Create a carousel of images for opt in requests
  • notification_message_tokens – Get a list of current notifications message tokens
  • notification_messages_cta_text – Customize the text for call to actions for opt in requests

The following ways to get opt ins for recurring notifications have been added:

October 3, 2022

The title field has been added to the Recurring Notfication webhooks notification.

August 16, 2022

Private Replies

Private Reply is now available for comments on Instagram Reels.

Instagram Messaging

You can now send Instagram messages with audio and videos that have been uploaded to a Meta server or sent from your server.

May 25, 2022

User Profile API supports retrieval of the customer's Instagram username field on Graph API v14.0 and later.

May 19, 2022

Recurring Notifications for Messenger API

Recurring Notifications is a major update to the Messenger API to allow businesses to send proactive, automated messages that drive re-engagement. Recurring Notifications help businesses deliver personalized, customer centric messages at every stage of the customer journey.

Recurring Notifications for Messenger API for Instagram

We’re announcing Recurring Notifications for Messenger API for Instagram as a beta. Developers can sign up for our beta interest list before July.

Instagram Send API rate limit increase

We have increased the rate limit for the Send API to 100 API calls per second for each Instagram Professional Account.

ig.me referral parameter

Businesses can add ig.me links on websites, emails, and product packaging to easily enable users to start a conversation with a business on Instagram. We are adding the ability for brands to add a referral parameter to these ig.me links to create personalized messaging experiences.

Instagram API New Onboarding Flow

We are announcing a new onboarding flow for the Instagram API as a beta. Developers can sign up for our beta interest list before June 29.

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 19, 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 and 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 14, 2022

As per the announcement on September 14, 2021, all Facebook pages will now be migrated to support the new Handover Protocol behavior. We expect to have all Pages migrated by March 18, 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 7, 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 11, 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 9, 2021

Oct 20, 2021

  • 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

  • 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 14, 2021. Developer should leverage page_label_name across various CRUD (Create, Retrieve, Update, Delete) API calls and webhooks.

  • Messenger API Updates for Europe and Japan - We have restored Customer Feedback Template in the Messenger API that wasn’t available to businesses in Europe, and for people in Europe and 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 14, 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 14, 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 16, 2021

  • 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 10, 2021

  • Messenger API Updates for Europe and 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 and Japan who connect with businesses globally. See the list of all restored features here.

Aug 6, 2021

  • 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 13, 2021.

Aug 4, 2021

  • 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 7, 2021

  • 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 22, 2021

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

June 8, 2021

The following changes apply to v11.0+

  • Adding <mid> to messaging_postback events for Messenger and 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 6, 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 2, 2021

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

Mar 30, 2021

  • 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

Dec 01, 2020

  • 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 16, several Messenger APIs will be unavailable for developers and businesses in Europe, and for people in Europe who connect with businesses globally.