This document contains the changelog for current versions of the Messenger Platform. The Messenger Platform follows Graph API Versioning.
The latest version is: v21.0
Components of this new Instagram API:
graph.instagram.com
instagram_business_basic
instagram_business_content_publishing
instagram_business_manage_comments
instagram_business_manage_messages
Visit our migration guide to learn if this new Instagram API with Instagram Login is right for you.
Monitor the Instagram Platform Changelog for changes including bug fixes and new features
ig_reel
will now be a supported attachment type for the messages webhook. IG reel attachments will have type ig_reel
and the attachment payload will include the title, url, and video id for the reel.
ig_reel
and reel
will now be supported attachment types in a messages webhook. IG reel attachments will have type ig_reel
, and the attachment payload will include the title, url, and video id for the reel. FB reel attachments will have type reel
, and the attachment payload will include the title, url, and video id for the reel.
Businesses using Messenger Conversation Routing can now configure the thread control takeover capability on the individual app level. The original takeover config that’s coupled with the default app is now deprecated with all values migrated. Learn more here.
Applies to all versions
In addition to the ad_id
and ad_title
, the original_media_id
will be returned in the media
object of the comments
field's value
object when a person comments on a boosted Instagram post or Instagram ads post. For more information, refer to Set Up Webhooks for Instagram.
message_edits
Webhook EventThe new message_edits
webhook event notifies you when a user edits a previously-sent message. Learn more about this webhook event here.
"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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Private Reply is now available for comments on Facebook Reels.
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.
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.
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
.
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.
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
.
Instagram Messaging is now available for any Instagram Professional account for a business or a Creator.
You can now add a call prompt to allow customers or people interested in your business to call your business.
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 is now available for Instagram Direct and Messenger.
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.
Messaging Insights API
New metrics and parameters are available for the Messaging Insights API.
Recurring Notifications for Messenger Platform
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.
Recurring Notifications for Messenger Platform
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.
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.
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.
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.
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.
We’ve made following up on Lead Gen ads that Click to Messenger easier through:
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 is now available for Instagram Messaging.
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.
You can now get a list of all valid Notification Message Tokens using the GET /PAGE-ID/notification_message_tokens
endpoint.
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 requestselements
– Create a carousel of images for opt in requestsnotification_message_tokens
– Get a list of current notifications message tokens notification_messages_cta_text
– Customize the text for call to actions for opt in requestsThe following ways to get opt ins for recurring notifications have been added:
The title
field has been added to the Recurring Notfication webhooks notification.
Private Reply is now available for comments on Instagram Reels.
You can now send Instagram messages with audio and videos that have been uploaded to a Meta server or sent from your server.
User Profile API supports retrieval of the customer's Instagram username field on Graph API v14.0 and later.
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 InstagramWe’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 increaseWe have increased the rate limit for the Send API to 100 API calls per second for each Instagram Professional Account.
ig.me referral parameterBusinesses 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 FlowWe 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.
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 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
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 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
).
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.
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.