Instagram API Setup
Admin walkthrough for Business Login for Instagram (Meta's "Instagram API with Instagram Login"). End-user flow: Connections → Instagram.
Once this page is filled in, Connect → Instagram sends the user to instagram.com: they sign in with the Instagram account itself, never see facebook.com, and no Facebook Page is involved. Leave it empty and Instagram silently falls back to the original Facebook-Page route documented in Facebook API Setup. Both routes are live at the same time — the callback path is the same for both.
Overview
| Form field | Options key |
|---|---|
| Instagram App ID | instagram_app-id |
| Instagram App Secret | instagram_app-secret |
| Status | instagram_integration_status |
ENV fallback: INSTAGRAM_APP_ID + INSTAGRAM_APP_SECRET.
This is not the Facebook App ID
Meta issues a separate app id/secret for Instagram Login, under the app's Instagram product. The Facebook App ID from Settings → Basic is rejected at instagram.com/oauth/authorize. Filling in only the Facebook pair on /admin/api-integration/facebook does not configure this page.
Step-by-step on developers.facebook.com
1. Open the Meta app
https://developers.facebook.com → My Apps. You can reuse the same Business-type app that already holds Facebook Login — only the credentials are separate — or create a new one.
2. Add the Instagram product
Add Product → Instagram, then open Instagram → API setup with Instagram business login.
3. Register the redirect URI
In API setup with Instagram business login → Business login settings:
- OAuth Redirect URIs: do not hardcode a domain. Copy the exact Callback URL shown on the admin page
/admin/api-integration/instagram(rendered live for this deployment). The pattern is:<BASE_URL>/api/v1/auth/instagram/callback<BASE_URL>is your backend URL;/api/v1is the configuredAPI_PREFIX. This is the same path the Facebook-Page route already uses — one entry serves both flows. See OAuth Callback URLs.
4. Required permissions
instagram_business_basic, instagram_business_content_publish, instagram_business_manage_insights. No pages_* permission is requested on this flow. Invited testers get them immediately in Development mode; going Live requires Meta App Review of each one.
5. Grab the Instagram App ID + App Secret
Same screen — Instagram → API setup with Instagram business login — shows Instagram app ID and Instagram app secret. Do not take them from Settings → Basic; those are the Facebook pair.
Pasting into Sosyabot admin panel
/admin/api-integration/instagram. Paste, Enable, Save, Test credentials.
Failure: Instagram login not configured: app id/secret missing (admin panel or INSTAGRAM_APP_ID/SECRET).
Account requirement
The person connecting needs an Instagram professional account — Business or Creator. No Facebook Page is required. A personal account is refused at the callback with the error instagram_not_professional, before any channel is written.
The old Facebook-Page route is unchanged: it still needs a Business / Creator account that is linked to a Facebook Page, and fails with no_instagram_business_account when it isn't.
The two routes side by side
| Instagram Login (this page) | Facebook Page (fallback) | |
|---|---|---|
| Consent screen | instagram.com | facebook.com |
| Facebook Page needed | No | Yes |
| Credentials | instagram_app-id / instagram_app-secret | facebook_app-id / facebook_app-secret |
| Token | Instagram user token, 60 days, self-renewing | Facebook Page token, no expiry |
| API host | graph.instagram.com/v21.0 | graph.facebook.com/v21.0 |
Sosyabot picks the route automatically: Instagram Login when this page is configured, Facebook Page otherwise. To force one for testing, append ?via=instagram or ?via=facebook to /api/v1/auth/instagram — ?via=instagram errors clearly if this page isn't configured. Which host an account uses is read off that account's stored token, so channels connected the old way keep working exactly as before.
Webhooks stay on the Facebook app
Meta webhooks (META_WEBHOOK_VERIFY_TOKEN) are unchanged and still verified with the Facebook app secret. Configuring this page does not move them.
Verification
/app/channels → Connect → Instagram → you should land on instagram.com (not facebook.com) → approve. Publish a one-image test post from /app/publishing.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Instagram login not configured: app id/secret missing (admin panel or INSTAGRAM_APP_ID/SECRET) | Admin + ENV empty, and ?via=instagram was forced | Steps 1–5. Without them Instagram uses the Facebook-Page route. |
| Connect still opens facebook.com | This page is empty or Status is Disabled → automatic fallback | Fill in the Instagram pair and set Status Enable. |
| instagram.com rejects the login with an invalid client id | The Facebook App ID was pasted here | Step 5 — take the id from Instagram → API setup with Instagram business login. |
Bounced back with instagram_not_professional | Personal Instagram account | Switch the account to Business or Creator in the Instagram app, then reconnect. |
Invalid redirect_uri at instagram.com | Callback not allow-listed | Add the exact …/api/v1/auth/instagram/callback under Business login settings (step 3). |
| Instagram channel dies around day 60 | The nightly refresh sweep isn't running | Confirm the worker (./service.sh logs worker); the sweep renews these tokens with grant_type=ig_refresh_token. Page-token channels are not affected. |
| App in Development mode and external users fail | Mode is gated to App Roles | Add testers under App Roles, or switch to Live mode (requires App Review). |
ENV fallback
INSTAGRAM_APP_ID=<your instagram app id>
INSTAGRAM_APP_SECRET=<your instagram app secret>Admin panel always wins. After editing .env run ./service.sh restart.