Instagram Direct
Instagram Direct is not a separate integration here. The Page is still the addressable thing: the conversation tools take a platform of MESSENGER or INSTAGRAM, and the same connected Page serves both inboxes.
That means one connection, one token, and one place to look at everything a customer sent you.
Three prerequisites, and only one of them is a permission
Instagram messaging fails silently more often than it errors, because two of the three requirements live outside the API.
1. A professional account, connected to the Page. A personal Instagram account cannot be read. The account must be a professional one (business or creator) and it must be connected to the Facebook Page you connected here.
2. The permissions. These are granted during connect, alongside the Page messaging ones. If you added them to the app after connecting, reconnect: the existing token was minted before the grant existed and does not carry it.
3. Allow Access to Messages — the one that wastes an afternoon. In the Instagram app itself:
Settings > Messages and story replies > Message controls
> Connected Tools > Allow Access to MessagesUntil that toggle is on, the permission reads as granted and the inbox comes back empty. There is no error to surface, because the API answers successfully with no data. An empty Instagram inbox on an account you know has messages is this setting until proven otherwise.
Two Instagram APIs, and which one this is
Meta offers two routes to Instagram messaging, and they are not interchangeable:
| Instagram API with Facebook Login | Instagram API with Instagram Login | |
|---|---|---|
| Identity | the Facebook Page | the Instagram account directly |
| Permissions | instagram_basic, instagram_manage_messages | the instagram_business_* family |
| Credentials | the app's existing id and secret | a separate Instagram app id and secret |
| Conversations | the Page's endpoint, platform=INSTAGRAM | Instagram's own host and endpoints |
This provider uses the Facebook Login route. One connection covers Messenger and Instagram together, one App Review submission covers both, and a Page that gains an Instagram account later needs no new integration.
The Instagram Login route is a genuinely different integration rather than a setting: different credentials, different authorization, different endpoints. If you have set that up in the app console, it does not feed this provider and nothing here will use it.
Reading it
Everything works the same as Messenger, with the platform named:
- list the threads with
platform: "INSTAGRAM" - read one thread by id, exactly as with Messenger
- each message names who sent it, so a reply from the account is distinguishable from a message from the customer
An account with no Instagram connected returns an error rather than an empty list. That distinction is useful: an error means no Instagram is attached, while an empty list means it is attached and something upstream — usually the toggle above — is holding the messages back.