Instagram
OAuth 2.0 via the Meta Graph API. Sosyabot uses the same Facebook app as the Facebook connector (requireFacebookCreds()); Instagram Business / Creator accounts are discovered through /me/accounts → instagram_business_account.
Authentication at a glance
| Field | Value |
|---|---|
| Auth model | OAuth 2.0 |
| Required ENV | FACEBOOK_APP_ID, FACEBOOK_APP_SECRET |
| Callback URL | ${BASE_URL}/api/v1/auth/instagram/callback |
| Scopes / permissions | instagram_basic, instagram_content_publish, instagram_manage_insights, pages_show_list, pages_read_engagement |
| Auto token refresh | No — manual reconnect on expiry |
ENV details
Same credentials as the Facebook connector — Meta apps are shared across the FB / IG / Threads family of products.
How to connect
- Open Connections → Instagram → Connect.
- Sign in to Facebook and grant the requested scopes.
- Pick the linked Page → Instagram Business Account on the post-connect screen.
Token refresh
Long-lived tokens are requested at connect time and not auto-refreshed. Reconnect manually if a token is invalidated.
Notes
- Personal Instagram accounts are not supported by Meta's publishing API — the account must be Business or Creator and linked to a Facebook Page.
- Token payload stores both the page access token and
pageId; posting calls hit the Page-scoped Instagram endpoints. - If the user has multiple linked Pages, Sosyabot creates one Sosyabot channel per Instagram Business Account discovered.
Troubleshooting
If the channel shows needs_reconnect, the access token was rejected by Instagram. Common causes:
- The user revoked Sosyabot's authorization on the platform.
- The platform invalidated the token (password change, security event).
- Your OAuth app credentials rotated and the existing tokens no longer match.
Re-run the connect flow above. See Troubleshooting for the workspace-wide checklist.