Facebook & Instagram API Setup
A walkthrough for instance administrators: create one Meta app on the Meta for Developers portal and use it for both Facebook and Instagram channel connections.
This is the admin-side doc. For the user-side flow see Connections → Facebook and Connections → Instagram.
Overview
Facebook and Instagram share a single Meta app — Sosyabot reuses one set of credentials for both. The admin form at /admin/api-integration/facebook writes:
| Form field | Options key |
|---|---|
| App ID | facebook_app-id |
| App Secret | facebook_app-secret |
| Status (Enable / Disable) | facebook_integration_status |
ENV fallback: FACEBOOK_APP_ID + FACEBOOK_APP_SECRET. There is no separate INSTAGRAM_* env block — Instagram resolves the same Meta credentials via requireFacebookCreds().
The admin panel for Instagram (/admin/api-integration/instagram) is informational and reuses the Facebook keys; you only configure once.
Step-by-step on developers.facebook.com
1. Create a Meta developer account
Go to https://developers.facebook.com, sign in with the Facebook account that should own the app, and complete the developer registration (phone verification).
2. Create a new app
My Apps → Create App. Pick app type Business (required for the page-publishing scopes you'll need). Provide a name and contact email.
3. Add products
In the new app's dashboard add these products:
- Facebook Login for Business — required for the OAuth flow.
- Instagram Graph API — required for Instagram Business / Creator publishing.
- (Optional) Threads — only if you'll also configure Threads later.
4. Configure OAuth redirect URI
Open Facebook Login for Business → Settings:
- Valid OAuth Redirect URIs:Self-hosters: substitute your
https://app.sosyabot.com/api/v1/auth/facebook/callback https://app.sosyabot.com/api/v1/auth/instagram/callbackBASE_URL. Both paths are required if you want both products to work. - Save.
5. Request the right permissions
App Review → Permissions and Features. Sosyabot needs:
pages_show_list,pages_read_engagement,pages_manage_posts,publish_video(Facebook publishing)instagram_basic,instagram_content_publish,instagram_manage_insights(Instagram publishing)
In Development mode you can use these immediately with App Roles testers. Going Live requires App Review for each permission — Meta needs a screencast showing how the permission is used.
6. Grab App ID + App Secret
Open Settings → Basic in the app dashboard. Copy App ID and App Secret (click Show on Secret).
App Secret rotation
Meta lets you regenerate the App Secret at any time. Doing so invalidates every existing Sosyabot-saved token and forces every connected user to reconnect. Only rotate if you must.
Pasting into Sosyabot admin panel
Open /admin/api-integration/facebook:
- App ID: paste from Settings → Basic.
- App Secret: paste the revealed secret.
- Status: Enable.
- Save → Test credentials. Success returns the App ID prefix + the resolved callback URL.
Failure messages:
Facebook integration disabled: app id/secret not configured→ both admin panel and ENV are empty.
Instagram inherits these settings
Once Facebook is configured you don't need to fill anything on /admin/api-integration/instagram — the same credentials are read by both connectors.
Verification — end-to-end smoke test
- From
/app/channelsconnect a Facebook Page (must be Page admin/editor on a page you control). - Approve scopes → bounce back, page listed as active.
- Publish a one-line test post from
/app/publishing; confirm on the page's public timeline. - Repeat with an Instagram Business / Creator account that's linked to a Facebook Page.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Facebook integration disabled: app id/secret not configured | Admin + ENV empty | Complete steps 5–6. |
Invalid OAuth redirect URI | Redirect URI not allow-listed | Add the exact …/api/v1/auth/facebook/callback (and …/instagram/callback) in Facebook Login → Settings. |
| Instagram connect succeeds but no accounts shown | The Facebook user isn't linked to an Instagram Business / Creator account on a Page they admin | Convert the Instagram account to Business / Creator and link it to a Facebook Page. |
| 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). |
Suddenly receiving 190 — Error validating access token | Token invalidated (password change, security event, App Secret rotated) | Affected users must reconnect from /app/channels. |
ENV fallback (self-hosters)
FACEBOOK_APP_ID=<your app id>
FACEBOOK_APP_SECRET=<your app secret>Read at boot from backend/src/config/env.ts. Admin panel always wins. After editing .env run ./service.sh restart api.