Instagram Platform

instagram_basic

Requires App Review.

The instagram_basic permission allows your app to read an Instagram Account profile's info and media.

Allowed Usage

  • Get basic metadata of an Instagram Business Account like username and ID.

instagram_content_publish

Requires App Review.

The instagram_content_publish permission allows your app to create organic feed photo and video posts on behalf of a business user.

Allowed Usage

  • Managing organic content creation process for Instagram (i.e. post photos, videos to main feed) on behalf of a business.

instagram_manage_comments

Requires App Review.

The instagram_manage_comments permission allows your app to create, delete, and hide comments on behalf of the Instagram Account linked to the Page. Your app can also read and respond to public media and comments that a business has been photo tagged or @mentioned in.

Allowed Usage

  • Read, update, and delete comments of Instagram Business Accounts.
  • Read media objects, such as stories, of Instagram Business Accounts.

instagram_manage_insights

Requires App Review.

The instagram_manage_insights permission allows your app to get access to insights for the Instagram account linked to the Facebook Page. You app can also discover and read the profile info and media of other business profiles.

Allowed Usage

  • Get metadata of an Instagram Business Account.
  • Get data insights of an Instagram Business Account.
  • Get story insights of an Instagram Business Account.

Live Video API

publish_video

Requires App Review.

Grants an app permission to publish live videos to the app User's timeline.

Allowed Usage

Live video streaming to a User's timeline.

Disallowed Usage

Streaming of advertisements, or any content which does not meet Facebook's content policies.

Messenger Platform

pages_messaging

Requires App Review.

The pages_messaging permission allows your app to manage and access Page conversations in Messenger. You can use this permission to create user-initiated interactive experiences, send customer support messages or to confirm bookings or purchases and orders.

Allowed Usage

  • Create interactive experiences initiated by a User.
  • Confirm customer interactions such as purchases, orders, and bookings.
  • Send customer support messages.

pages_user_gender

Requires App Review.

The pages_user_gender permission allows your app access to a user's gender through the Page your app is connected to. You can use this permission to personalize the experience of people interacting with your Messenger integration.

Allowed Usage

  • Personalize experiences or recommendations based on gender.
  • Use gendered language such as correct pronouns and titles.

pages_user_locale

Requires App Review.

The pages_user_locale permission allows your app access to a user's locale through the Page your app is connected to. You can use this permission to personalize the experience of people interacting with your Messenger integration.

Allowed Usage

  • Personalize experiences or recommendations based on gender.
  • Use gendered language such as correct pronouns and titles.

pages_user_timezone

Requires App Review.

The pages_user_timezone permissions grants your app access to a user's time zone through the Page your app is connected to. You can use this permission to personalize the experience of people interacting with your Messenger integration.

Allowed Usage

  • Prevent messages from being sent at an inconvenient time.
  • Send time sensitive content or recurring news at a specific time.
  • Provide tailored content based on time.
  • Send time appropriate greetings.

Pages and Business Assets

ads_management

Requires App Review.

The ads_management permission allows your app to both read and manage the ads account it owns, or has been granted access to by the ad account owner.

Allowed Usage

  • Programmatically create campaigns, manage ads, and fetch metrics.
  • Build ad management tools that provide innovative solutions and differentiated value for advertisers.

ads_read

Requires App Review.

The ads_read permission allows your app to access the Ads Insights API to pull ads report information for ad accounts you own or have been granted access to by the owner, or owners, of other ad accounts through this permission. This permissions also grants your app access to the Server-Side API to allow advertisers to send web events from their servers directly to Facebook.

Allowed Usage

  • Provide API access to your ad performance data for use in custom dashboards and data analytics.
  • Send web events from your server directly to Facebook.

attribution_read

Requires App Review.

The attribution_read permission grants your app access to the Attribution API to pull attribution report data for lines of business you own or have been granted access to by the owner or owners of other lines of business. You can use this permission to provide the ability for your app to access ad performance data from attribution for use in custom dashboards and data analytics. Note: Requires the ads_read and business_management permissions to work correctly.

Allowed Usage

  • Provides the ability for your app to access ad performance data from Attribution for use in custom dashboards and data analytics.

business_management

Requires App Review.

The business_management permission allows your app to read and write with the Business Manager API.

Allowed Usage

  • Manage business assets such as an ad account.
  • Claim ad accounts.

catalog_management

Requires App Review.

The catalog_management permission allows your app to create, read, update and delete business-owned product catalogs that the user is an admin of. You can use this permission to build commerce-related solutions for ecommerce platforms, travel platforms and dynamic ads. It can also be used to build inventory type management solutions like product inventory, hotel inventory or car inventory.

Allowed Usage

  • Build commerce-related solutions like ecommerce platforms, travel platforms and dynamic ads.
  • Build inventory type management solutions like product inventory, hotel inventory or car inventory.

leads_retrieval

Requires App Review.

The leads_retrieval permission allows your app to retrieve and read all information captured by a lead ads form associated with an ad created in Ads Manager or the Marketing API.

Allowed Usage

  • Reach out to the people who followed up your lead ad form requesting more information. For example, an auto dealer reaching out to a potential customer (lead) that responded to their ad with quotes for a car.
  • For advertiser authorized CRM platforms to pull the lead data on behalf of the advertisers. These advertisers can then use the lead information to reach out to the user.

manage_pages

On May 5, 2020, we released six new Page permissions to replace the manage_pages and publish_pages permissions. The manage_pages permission has been replaced with pages_manage_ads, pages_manage_metadata, pages_read_engagement, and pages_read_user_content. The publish_pages permission has been replaced with pages_manage_posts and pages_manage_engagement.

Please visit our V7.0 Blog post, Graph API Changelog, and Pages API Overview for more information.

Requires App Review.

The manage_pages permission allows your app to retrieve Page Access Tokens for the Pages and apps that the app user administers.

Allowed Usage

  • Help people analyze or manage the posts, comments and likes published to their Pages.
  • Publish content to Pages owned by the people who use your app. Note: Publishing also requires the publish_pages permission.

pages_manage_ads

Requires App Review.

The pages_manage_ads permission allows your app the ability to manage ads associated with the Page. You can use this permission to create and manage ads for the Page.

Allowed Usage

  • Create ads for your Page.
  • Manage ads for your Page.

pages_manage_cta

Requires App Review.

The pages_manage_cta permission allows your app to carry out POST and DELETE functions on endpoints used to manage a Facebook Page's call-to-action buttons.

Allowed Usage

  • Provide API access to manage call-to-action buttons on Pages that you manage.

pages_manage_engagement

Requires App Review.

The pages_manage_engagement permission allows your app the ability to create, edit, and delete comments posted on the Page. If you have access to pages_read_user_content, you can also use pages_manage_engagement to delete comments posted by other Pages. It also allows your app the ability to create and delete your own Page's likes to Page content. You can use this permission if you need it to help manage and moderate content on the Page.

Allowed Usage

  • Publish a comment on a Page post.
  • Update your comment on a Page post.
  • Delete a comment on a Page post.
  • Like a Page post or remove your like from a Page post.

pages_manage_instant_articles

Requires App Review.

The pages_manage_instant_articles permission allows your app to manage Instant Articles on behalf of Facebook Pages administered by people using your app.

Allowed Usage

  • Create and update Instant Articles for Pages owned by the people who use your app.

pages_manage_metadata

Requires App Review.

The pages_manage_metadata permission allows you to subscribe and receive webhooks about activity on the Page, and to update settings on the Page. You can use this permission if you need it to help the Page Admin administer and manage the Page.

Allowed Usage

  • Subscribe to receive webhooks of your Page.
  • Update settings of your Page.

pages_manage_posts

Requires App Review.

The pages_manage_posts permission allows your app the ability to create, edit, and delete your Page posts. If you have access to pages_read_user_content, you can also use pages_manage_posts to delete Page posts created by a User. You can use this permission to create and delete content on the Page.

Allowed Usage

  • Publish a post, photo, or video to your Page.
  • Update a post, photo, or video on your Page.
  • Delete a post, photo, or video on your Page.

pages_read_engagement

Requires App Review.

The pages_read_engagement permission allows your app the ability to read content (posts, photos, videos, events) posted by the Page, read followers data including name, PSID, and profile picture, and read metadata and other insights about the Page. You can use this permission if you need it to help the Page Admin administer and manage the Page.

Allowed Usage

  • Get content posted by your Page.
  • Get names, PSIDs, and profile pictures of your Page followers.
  • Get metadata about your Page.

pages_read_user_content

Requires App Review.

The pages_read_user_content permission allows your app the ability to read User generated content on the Page, such as posts, comments, and ratings by Users or other Pages, and to delete User comments on Page posts. It also allows your app to read posts that the Page is tagged in. You can use this permission to read Users and other Page’s content posted on the Page if you need it to help manage the Page.

Allowed Usage

  • Get User generated content on your Page.
  • Get posts that your Page is tagged in.
  • Delete comments posted by Users on your Page.

pages_show_list

Does not require App Review.

The pages_show_list permission allows your app to show the list of the Pages that a person manages.

Allowed Usage

  • Provide API access to accounts for showing the list of the Pages that a person manages.

publish_pages

On May 5, 2020, we released six new Page permissions to replace the manage_pages and publish_pages permissions. The manage_pages permission has been replaced with pages_manage_ads, pages_manage_metadata, pages_read_engagement, and pages_read_user_content. The publish_pages permission has been replaced with pages_manage_posts and pages_manage_engagement.

Please visit our V7.0 Blog post, Graph API Changelog, and Pages API Overview for more information.

Requires App Review.

The publish_pages permission allows your app to publish posts, comments and like Pages managed by the app user.

Allowed Usage

  • Allow app users to explicitly publish content from your app to any of the Facebook Pages they manage from within a custom composer.
  • Like and comment from your app on behalf of the Pages app users manage.

read_insights

Requires App Review.

The read_insights permission allows your app to read the Insights data for Pages, apps, and web domains the person owns.

Allowed Usage

  • Integrate Facebook's app, page or domain insights into your own analytics tools.

User Data

Default Public Profile Fields

Does not require App Review.

Grants your app access to the default fields of the User object that are a subset of a person's public profile:

  • id
  • first_name
  • last_name
  • middle_name
  • name
  • name_format
  • picture
  • short_name

email

Does not require App Review.

The email permission allows your app to read an end user's primary email address. This permission is automatically granted to all apps.

Allowed Usage

  • Communicating with people and letting them log into your app with the email address associated with their Facebook profile.

groups_access_member_info

Requires App Review.

The groups_access_member_info permission allows your app to read publicly available group member information like name and ID if the post author has granted your app access.

Allowed Usage

  • Allow apps to get content posted in their group with user details.
  • Help admins get aggregated insights about activity happening in their group.

publish_to_groups

Requires App Review.

The publish_to_groups permission allows your app to post content into a group on behalf of a person if they've granted your app access.

Allowed Usage

  • Allow people to publish content from your app to their Facebook group.
  • Help people manage the content published to their group.

user_age_range

Requires App Review.

Grants an app permission to access a person's age range.

Allowed Usage

Your app includes content that is legally required to be age-gated, for example, gambling, gaming, or alcohol.

Your app includes content that is not suitable for the general Facebook audience, such as dating, mature, graphic, or violent content.

Your application includes content that is directed at kids or teens.

Disallowed Usage

No visible impact to the User experience based on a person's age range.

user_birthday

Requires App Review.

The user_birthday permission allows your app to read a user's birthday as listed in their Facebook profile.

Allowed Usage

  • Provide age relevant content to people when their age range is not sufficient.

user_friends

Requires App Review.

The user_friends permission allows your app to get a list of a user's friends using that app. You can use this permission to provide Facebook related content to personalize a persons experience.

Allowed Usage

  • Providing Facebook-related content to personalize a person's experience.

user_gender

Requires App Review.

Grants an app permission to access a person's gender.

Allowed Usage

Correctly render pronouns in certain languages, for example, when a bot messages a person.

Display a person's gender to other people, for example, for dating.

Personalized a User's experience based on gender, for example, in shopping or fashion.

Disallowed Usage

No visible impact to the user experience based on gender.

Fill out a registration form or User profile without using the information to enhance the User experience.

user_hometown

Requires App Review.

The user_hometown permission allows your app to read a user's hometown location from their Facebook profile.

Allowed Usage

  • Provide a personalized experience based on where a person lived or grew up.

user_likes

Requires App Review.

The user_likes permission allows your app to read a list of all Facebook Pages that a user has liked. You can use this permission to provide a personalized experience by correlating or surfacing content related to the the person's likes. This includes curating content at scale to customize apps with large amounts of content and to enable people to share their likes with others, such as in the case of dating and music apps.

Allowed Usage

  • Provide a personalized experience by correlating or surfacing content related to the person's liked interests. This includes curating content at scale to customize apps with large amounts of content.
  • Enable people to share their like interests with other such as in the case of dating and music apps.

Requires App Review.

The user_link permission allows your app to access the Facebook profile URL of the person using your app.

Allowed Usage

  • Provide a way for someone who uses your app to visit that person's Facebook profile.

user_location

Requires App Review.

The user_location permission allows your app to read the city name as listed in the location field of a person's Facebook profile.

Allowed Usage

  • Provide a personalized experience based on the city name as listed in the location field of a person's Facebook profile.

user_photos

Requires App Review.

The user_photos permission allows your app to read the photos a person has uploaded to Facebook.

Allowed Usage

  • Create physical or digital books of albums of a person's photos, which includes permitting people to export photos for printing.
  • Provide people with the ability to display their photos with others within the app, like in dating or social apps.
  • Provide people with the ability to edit or create new photo content based on existing photos.

user_posts

Requires App Review.

The user_posts permission allows your app to access the posts that person has made on their timeline.

Allowed Usage

  • Enable people to create physical or digital books or albums of their timelines.
  • Enable people to share memories from their timeline with their friends.
  • Enable people to share their posts with other social apps.

user_videos

Requires App Review.

The user_videos permission allows your app to read a list of videos uploaded by a user.

Allowed Usage

  • Display a person's videos on a TV via a set-top box or display their videos in a digital photo frame.
  • Provide people with the ability to edit or create new video content using existing videos.
  • Provide people with the ability to display their video with owners within their app, like in dating or social apps.

WhatsApp Platform

whatsapp_business_management

Requires App Review.

The whatsapp_business_management permission lets your app read and/or manage WhatsApp business assets you own or have been granted access to by other businesses through this permission. These business assets include WhatsApp business accounts, phone numbers, and message templates. You can use this permission to display WhatsApp Business Account analytics in your customer portal or to manage message templates for WhatsApp Business Accounts.

Allowed Usage

  • Display WhatsApp Business Account analytics in your customer portal.
  • Manage message templates for WhatsApp Business Accounts.