Business Login for Instagram

Business Login for Instagram is a custom, manual Facebook Login flow that makes it easier for you to onboard Instagram users who still need to configure their account for API access.

In order to make their account accessible to our APIs, Instagram users must first convert their account to a Professional account, create a Facebook Page that represents their business, then connect that Page to their account.

Business Login for Instagram simplifies this process by allowing Instagram users to complete all of these steps in a single window instead of having to complete them in the Facebook and Instagram apps.

Before You Start

Add the Facebook Login product to your app and add a redirect URL. We will redirect users to this URL after they complete the onboarding flow.

1. Go to the Apps Panel and select your app to load it in the App Dashboard.
2. In the left-hand menu, click Add Products, locate Facebook Login, then click Set Up to add it to your app.
3. In the left-hand menu under Facebook Login, click Settings.
4. In the Client OAuth Settings > Valid OAuth Redirect URIs field, enter your redirect URL.

Step 1: Construct the Login URL

Construct the Business Login URL using its base URL and query string parameters.

URL Syntax

https://www.facebook.com/dialog/oauth
  ?client_id={client-id}
  &display={display}
  &extras={extras}
  &redirect_uri={redirect-uri}
  &response_type={response_type}
  &scope={scope}

Query String Parameters

All parameters are required.

Example URL

This is an example of a URL constructed by an app that relies on the Instagram Messaging API and has therefore requested permissions required by Messaging API endpoints.

https://www.facebook.com/v19.0/dialog/oauth?client_id=442224939723604&display=page&extras={"setup":{"channel":"IG_API_ONBOARDING"}}&redirect_uri=https://my-clever-redirect-url.com/success/&response_type=token&scope=instagram_basic,instagram_content_publish,instagram_manage_comments,instagram_manage_insights,pages_show_list,pages_read_engagement

Step 2: Assign the URL to a Button

Assign the URL to a standard anchor link or button of your own design and display it to any users who you are certain have not completed the onboarding flow.

Example Anchor Link

<a href="https://www.facebook.com/v19.0/dialog/oauth?client_id=442224939723604&display=page&extras={"setup":{"channel":"IG_API_ONBOARDING"}}&redirect_uri=https://my-clever-redirect-url.com/success/&response_type=token&scope=instagram_basic,instagram_content_publish,instagram_manage_comments,instagram_manage_insights,pages_show_list,pages_read_engagement">Login to Facebook</a>

Step 3: Capture User access token

After a user clicks your link or button and completes the Business Login for Instagram flow, we will redirect the user to the URL you assigned to the redirect_uri. We will also append a URL fragment (#) with the user's short-lived User access token, some metadata about the token, and the user's long-lived access token. Capture the long-lived access token.

Canceled Login

If a user cancels out of the login flow we will still redirect the user to your redirect_uri but append different data. Refer to the Manually Build a Login Flow document's Canceled Login section to learn how process these redirects.

Redirect Syntax

{redirect-url}?
  #access_token={access-token}
  &data_access_expiration_time={data-access-expiration-time}
  &expires_in={expires-in}
  &long_lived_token={long-lived-token}

Fragment Providers

Token values have been truncated (...) in this example for readibility.

Example Redirect

Token values have been truncated (...) in this example for readability.

https://my-clever-redirect-url.com/success/?#access_token=EAAHm...&data_access_expiration_time=1658889585&expires_in=4815&long_lived_token=ABAEs...

Step 4: Get the User's Page, Page Access Token, and Instagram Business Account

Send a request to the GET /me/accounts endpoint and request the following fields:

• id
• name
• access_token
• instagram_business_account

This will return a collection of Facebook Pages that the user can perform tasks on. For each Page in the result set, the response will include its:

• ID
• Name
• Page access token
• Instagram Business account ID connected to the Page

cURL Example

Token values have been truncated (...) in this example for readability.

curl -i -X GET \
 "https://graph.facebook.com/v19.0/me/accounts?fields=id%2Cname%2Caccess_token%2Cinstagram_business_account&access_token=EAACw..."

Example Response

Token values have been truncated (...) in this example for readability.

{
  "data": [
    {
      "id": "134895793791914",
      "name": "Metricsaurus",
      "access_token": "EAACw...",
      "instagram_business_account": {
        "id": "17841405309211844"
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "MTc1NTg0Nzc2ODAzNDQwMgZDZD",
      "after": "MTc1NTg0Nzc2ODAzNDQwMgZDZD"
    }
  }
}

Capture the Page ID (id), Page access token (access_token), and Instagram Professional account ID (instagram_business_account) for the Page that the user has connected to their Instagram Professional account.

Keep in mind that some users may be able to perform tasks on more than one Page. If multiple Pages are included in the response, you may have to surface each Page's name (name) to the user so they can identify which Page's data to capture.

Conclusion

You should now have everything you need to help your access and work with their data using our various APIs:

• Instagram Business account ID
• ID of the Facebook Page connected to the Instagram Business account
• the Facebook Page's access token (required by the Instagram Messaging API)
• a User access token from the user, who is able to perform tasks on the Facebook Page connected to the Instagram Business account (required by the Instagram Graph API)