This document explains how to successfully call Messenger API support for Instagram (also known as Instagram Messaging API in our Developer Policies) with your app and get Instagram Professional account messages. It assumes you are familiar with the Graph API and Facebook Login.
You will need access to the following:
MODERATE
task on that Page Developers that are new to the Messenger Platform
Developers with prior experience on the Messenger Platform
You can use Facebook Login or Business Login for Instagram to ask your app users for the need permissions.
The Business Login for Instagram flow allows a person to complete the following during the login flow:
To implement Business Login for Instagram, visit our Business Login for Instagram guide then return to this guide.
Make sure you are signed into your Facebook Developer account, then access your app and trigger the Facebook Login modal. Remember, your Facebook Developer account must be able to perform Tasks with atleast "Moderate" level access on the Facebook Page connected to the Instagram account you want to query.
Once you have triggered the modal, click OK to grant your app the instagram_basic
, instagram_manage_messages
, and pages_manage_metadata
permissions.
The API should return a User access token. Capture the token so your app can use it in the next few queries. If you are using the Graph API Explorer, it will be captured automatically and displayed in the Access Token field for reference:
Query the GET /me/accounts
endpoint (this translates to GET /{user-id}/accounts
, which perform a GET on the Facebook User node, based on your access token).
curl -i -X GET \ "https://graph.facebook.com/v9.0/me/accounts?access_token={access-token}"
This should return a collection of Facebook Pages that the current Facebook User can perform the MANAGE
, CREATE_CONTENT
, MODERATE
, or ADVERTISE
tasks on:
{ "data": [ { "access_token": "EAAJjmJ...", "category": "App Page", "category_list": [ { "id": "2301", "name": "App Page" } ], "name": "Metricsaurus", "id": "134895793791914", // capture the Page ID "tasks": [ "ANALYZE", "ADVERTISE", "MODERATE", "CREATE_CONTENT", "MANAGE" ] } ] }
Capture the ID of the Facebook Page that's connected to the Instagram account that you want to query. Keep in mind that your app users may be able to perform tasks on multiple pages, so you eventually will have to introduce logic that can determine the correct Page ID to capture (or devise a UI where your app users can identify the correct Page for you).
In order to perform various Instagram Messaging API calls, you will need to use the associated Page Access Token (PAT) of the relevant Instagram Professional account that has been previously granted via FB login flow.
Send a GET
request to the /{page-id}
endpoint using your User access token. For example:
curl -i -X GET "https://graph.facebook.com/{page-id}? fields=access_token& access_token={user-access-token}"
On success, your app gets this response:
{ "access_token":"{page-access-token}", "id":"{page-id}" }
To generate a long-lived Page access token, you can follow the guide here.
This tool is currently being rolled out to all developers over the coming weeks. If you don't see the settings under the App Dashboard, you can leverage Step 1-5 above to generate Page Access Tokens.
Optionally, if you own the assets(Instagram account and FB page) that you want to onboard to Messenger API support for Instagram, you can leverage the Instagram setup tool under the Developer App Dashboard to allow you to easily setup Page Access Tokens and Webhooks. You can find the tool under Developer app dashboard → Messenger → Instagram Settings. Existing way of configuring tokens and webhook will still work, but this tool will give you an easier way to setup your environment.
In order to manage Instagram messages via API, Instagram Professional accounts will need to enable the connected tools toggle under message control settings.
Use the Page ID you captured and the Page Access Token (PAT) to query the GET /{page-id}/conversations?platform=instagram
endpoint:
curl -i -X GET \ "https://graph.facebook.com/v9.0/17841405822304914/conversations?platform=instagram&access_token={access-token}"
This should return the IDs of all the thread objects on the Instagram user:
{ "data": [ { "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTM2MDk5MDc1MzYyOTgx" }, { "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTYzMzQ2MzE5NjM1NDcy" }, { "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTk3MTY0NjI2NzAyMjMw" }, { "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MzkzNDI5MDYzMzkyNjU0" } }
If you can perform this final query successfully, you should be able to perform queries using any of the Messenger API support for Instagram endpoints - just refer to our various guides and references to learn what each endpoint can do and what permission they require.