Facebook API Setup

A walkthrough for instance administrators: create a Meta app on the Meta for Developers portal and use it for Facebook Page channel connections.

This is the admin-side doc. For the user-side flow see Connections → Facebook.

Instagram is configured on its own page

Instagram no longer runs on these credentials by default. Its normal connect route is Business Login for Instagram, which needs a separate Instagram App ID + App Secret — set those up on Instagram API Setup.

The app you configure here still powers Instagram's fallback route, the original one that connects an Instagram account through a Facebook Page. That fallback runs automatically when no Instagram credentials are configured, and can be forced with ?via=facebook.

Overview

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.

These credentials cover Facebook Pages and the Instagram fallback route. Meta webhooks are also verified against this app's secret — configuring an Instagram app does not move them.

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 — only if you want the Instagram fallback route (Instagram via a Facebook Page). Business Login for Instagram does not use this app.
• (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: do not hardcode a domain. The admin page /admin/api-integration/facebook shows the exact Callback URL for this deployment — copy it byte-for-byte. The pattern is:

  <BASE_URL>/api/v1/auth/facebook/callback

  Add the Instagram callback here only if you want the fallback route to work:

  <BASE_URL>/api/v1/auth/instagram/callback

  <BASE_URL> is your backend URL; /api/v1 is the configured API_PREFIX. See OAuth Callback URLs.
• 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 — only for the Instagram fallback route. Business Login for Instagram asks for its own instagram_business_* permissions on the Instagram app instead.

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:

1. App ID: paste from Settings → Basic.
2. App Secret: paste the revealed secret.
3. Status: Enable.
4. 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.

Verification — end-to-end smoke test

1. From /app/channels connect a Facebook Page (must be Page admin/editor on a page you control).
2. Approve scopes → bounce back, page listed as active.
3. Publish a one-line test post from /app/publishing; confirm on the page's public timeline.
4. Only if you set up the fallback route: 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 in Facebook Login → Settings (and …/instagram/callback if you use the fallback route).
Instagram connect sends the user to facebook.com instead of instagram.com	No Instagram credentials configured, so the connect route fell back	Configure Instagram API Setup.
Instagram fallback connect succeeds but no accounts shown (no_instagram_business_account)	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 — or connect it through Business Login instead, which needs no 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.

Related

Instagram API Setup

OAuth Credentials overview

Facebook user-side connect