Overview

Instagram messaging on Messenger Platform is a collection of Facebook Graph API endpoints that allow apps to access and manage messages of Instagram Business 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 Business 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 business's instagram messages.

Access Tokens

App user authentication is handled through access tokens. Instagram Business 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.

Pages

Instagram Business 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 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 Business Account help article explains how to connect to a Facebook Page to an Instagram Business account.

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. If your app will only be used by app users who have a Role on your app or Business, you do not need to complete App Review. 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 Instagram Messaging 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.

The send API rate limit for each Instagram business account is 200 messages/5 minutes. Developers should fallback gracefully when the rate limit is reached and space out API calls.

If the combined rate of Send and Receive (Webhooks) of an individual Instagram business account is more than 300 messages/5 minutes, webhooks might be delayed. The delay will increase if the combined rate keeps exceeding the limit.

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 business account. IGSID is used throughout Instagram Messaging 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 Business 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 Instagram Messaging concepts, you can proceed to the Getting Started section and start building your Instagram Messaging experiences.