Meta setup (Facebook & Instagram)

One Meta app covers both Facebook Pages and Instagram business accounts.

Facebook and Instagram publishing both go through the Meta Graph API, so a single Meta app serves both. SocialRelay reads FACEBOOK_CLIENT_ID and FACEBOOK_CLIENT_SECRET, and Instagram falls back to those values unless you set INSTAGRAM_CLIENT_ID and INSTAGRAM_CLIENT_SECRET separately.

Meta publishing has real prerequisites

Facebook posts go to a Page, never a personal profile. Instagram publishing requires a business or creator account that is linked to one of those Pages. Without both, the connect flow completes but no publishable target is found.

Prerequisites

A Facebook Page you administer
For Instagram: an Instagram business or creator account, linked to that Page in Meta Business Suite
A Meta developer account at developers.facebook.com

1. Create the app

In the Meta developer dashboard choose Create App.
Pick the Business app type. It is the one that exposes Pages and Instagram publishing.
Connect it to a Business portfolio if you are prompted.

2. Add Facebook Login

Add the Facebook Login for Business product.
Under its settings, enable Client OAuth login and Web OAuth login.
Add both redirect URIs:

text

https://social.aitoolbucket.com/api/oauth/facebook/callback
https://social.aitoolbucket.com/api/oauth/instagram/callback

Meta requires HTTPS

Redirect URIs must be HTTPS. For local development, tunnel your dev server through something like ngrok and register that hostname as an additional URI rather than http://localhost.

3. Permissions

SocialRelay requests exactly these:

Permission	Why it is needed
`pages_show_list`	List the Pages you manage, so one can be chosen at connect time
`pages_read_engagement`	Read Page metadata, and confirm a published post exists
`pages_manage_posts`	Create the post. This is the one that actually publishes
`business_management`	Resolve Pages that belong to a Business portfolio
`instagram_basic`	Read the linked Instagram business account and its username
`instagram_content_publish`	Create and publish Instagram media containers

4. Copy the credentials

From App settings → Basic, take the App ID and App Secret.

bash

cd /var/www/creator

read -rsp "FACEBOOK_CLIENT_ID: " V && printf '\nFACEBOOK_CLIENT_ID="%s"\n' "$V" >> .env
read -rsp "FACEBOOK_CLIENT_SECRET: " V && printf '\nFACEBOOK_CLIENT_SECRET="%s"\n' "$V" >> .env

sudo systemctl restart creator-app creator-worker

5. Test before review

While the app is in development mode, publishing works for Pages owned by people who hold a role on the app — you, and anyone you add under App roles. That is enough to verify the whole pipeline end to end without waiting on Meta.

6. App review

To publish to Pages owned by anyone else, submit pages_manage_posts and instagram_content_publish for App Review. Meta will want a screencast showing the real flow: signing in, choosing a Page, composing, and publishing. Business verification is generally required too.

Your privacy policy and data deletion URLs

Meta requires both before review. This deployment already serves them at /privacy and /data-deletion.

Troubleshooting

“No Facebook Page is available on this account”

The signed-in user administers no Page, or did not grant access to one during the consent step. Meta’s dialog lets people deselect Pages — reconnect and make sure the Page is ticked.

“No Instagram business account is linked to your Facebook Pages”

The Instagram account is either personal, or not linked to a Page. Convert it to a business or creator account and link it in Meta Business Suite, then reconnect.

`FACEBOOK_TOKEN_EXPIRED` or `INSTAGRAM_TOKEN_EXPIRED`

Meta invalidates tokens when a password changes, when permissions are revoked, or when the user’s Page role is removed. Reconnect the account. Page access tokens derived from a long-lived user token do not expire on a timer, so a sudden expiry usually means one of those events.

`FACEBOOK_PERMISSION_DENIED`

Either pages_manage_posts was not granted, or the app is in development mode and the Page belongs to somebody without a role on the app.

`INSTAGRAM_CONTAINER_FAILED`

Instagram processes media asynchronously; SocialRelay polls the container until it is ready and reports this if it errors or never finishes. The usual causes are an image URL Meta cannot fetch, or an unsupported aspect ratio. Confirm the URL is publicly reachable over HTTPS.

Next: TikTok setup, or connect an account with the Facebook connection guide.