Overview

Messenger API support for Instagram (also known as Instagram Messaging API in our Developer Policies) is a collection of Facebook Graph API endpoints that allow apps to access and manage messages of Instagram Professional accounts. If you are unfamiliar with the Facebook Graph API, please read the Graph API documentation before proceeding.

Host URL

All endpoints can be accessed via the graph.facebook.com host.

App Users

Instagram Professional accounts are accessed indirectly through Facebook accounts so your app users must have a Facebook account and use it when signing into your app and granting the appropriate permission to allow your app to manage the Instagram account's messages.

Access Tokens

App user authentication is handled through access tokens. Instagram Professional accounts are accessed through Facebook accounts, and not Instagram credentials. As a result, all API requests must include your app user’s Facebook access token. To get the Facebook token for a user, you must implement Facebook Login for your app, and users must sign in with their Facebook account.

Permissions

Endpoint authorization is handled through Permissions. The API uses the following Permissions and Features:

You must implement Facebook Login in order to request Permissions from your app users. All of these Permissions can be granted by any app user who has a Role on your app or a Role on a Business that has claimed your app while it is in Development Mode. However, your app must be approved for these Permissions through the App Review process before app users can grant them to your app while it is in Live Mode.

In order to use Instagram Messaging APIs, the page access token generated must have both instagram_manage_messages and instagram_basic scope regardless of your app types (devmode/livemode or standard/advance mode).

Pages

Instagram Professional Account must be connected to a Facebook Page before their data can be accessed through the API. Once connected, any Facebook User who is able to perform Tasks with atleast "Moderate" level access on that Page can grant your app an access token, which can then be used in API requests. Our Add a Facebook Page to your Instagram Professional Account help article explains how to connect to a Facebook Page to an Instagram Professional account.

Testing Your App Before App Review

While the app is in development mode/ standard access, all Instagram Messaging APIs (Send API, Webhook, Conversation API, etc.) will only work for users that have a role in the app. The page access token generated must have both instagram_manage_messages and instagram_basic scope regardless of your app types (devmode/livemode or standard/advance mode)

Users that have a role in the app has to fulfill one of the following requirements:

  • The IG account has a connected FB account with a tester role on the app (i.e. the IG account connected to the FB tester will work as an IG tester account)
  • The IG account has a connected FB account that has an app admin role
  • The IG account has a connected FB account that has a role of an app developer

The following behaviors will apply for Messenger API support for Instagram:

  • Send API will only work for users that have a role in the app.
  • Webhook will only be delivered for users that have a role in the app.
  • Conversation API will only be showing threads/messages for users that have a role in the app.

App Review

Your app must complete App Review before it can be used by app users who do not have a Role on your app or a Role on a Business that has claimed your app. Your App Review submission does not need to include any Facebook test user credentials if you have implemented Facebook Login and your app is publicly available. However, if our reviewers need to sign into a non-Facebook account in order to trigger your implementation of Facebook Login, you must include the non-Facebook account credentials in your submission.

Refer to Messenger API support for Instagram App Review guidance for more details on requirements for app review submission.

Business Verification

You must complete Business Verification if your app will be used by app users who do not have a Role on the app itself, or a Role in a Business that has claimed the app.

Rate Limiting

All endpoints are subject to Messenger Business Use Case rate limiting.

A rate limit is the number of API calls an app or user can make within a given time period. If this limit is exceeded, the app or user may be throttled. API requests made by a throttled user or app will fail. For more details on rate limit, refer to here.

Webhooks

You can use Webhooks to have notifications sent to you whenever someone comments on your app users' media objects or when any of their stories expire. Refer to our Webhooks documentation to learn how to use Webhooks, then set up a webhook for the Instagram topic and subscribe to its messages field.

IGSID

IGSID is an Instagram (IG)-scoped ID assigned to each user that messages an Instagram Professional account. IGSID is used throughout Messenger API support for Instagram to enable you to identify the user associated with sent and received messages. IGSID is a unique mapping/hash between the Instagram user ID and the Instagram Professional account. You should use IGSID as a primary identifier in your backend system instead of username because an IG username can be changed by the user.

Next Steps

After you are familiar with various Messenger API support for Instagram concepts, you can proceed to the Getting Started section and start building your Messenger API support for Instagram experiences.