Meta Developer settings#

The platform uses one Meta Developer App for every client. You configure it once at Settings → Meta Developer (/super-admin/settings/meta-developer-settings), and every client authorization falls back to these credentials server-side. Clients connect with "Continue with Facebook" — they never type an App ID or Secret.

Who this is for#

The person who owns the Meta Developer App (usually a Super Admin or the platform developer). This is an operator-only surface — the strings are deliberately plain to help non-developers.

• Difficulty: Advanced
• Time: 15 min
• Prerequisites: A Meta Developer account, an app created at developers.facebook.com, and access to your domain's public URL settings.

Step 1 — Create the app on Meta's side#

1. Log in at developers.facebook.com and create an app (type: Business).
2. Note the App ID and App Secret from Settings → Basic.
3. In the app's Facebook Login settings, add the OAuth redirect URI shown on the Meta Developer page (see step 3).
4. Add the lead permissions the connect flow uses: leads_retrieval, pages_show_list, pages_read_engagement, pages_manage_ads.

Step 2 — Enter the credentials#

On Settings → Meta Developer, under App Configuration:

Step 3 — Copy the OAuth redirect URI into Meta#

The page shows the OAuth redirect URI to use. On this install it resolves to:

https://<your-domain>/oauth/meta/callback

Copy it into the Meta Developer App under Facebook Login → Settings → Valid OAuth Redirect URIs. If this does not match, client connections fail at the final step with an error from Meta.

Step 4 — Run Test Connection#

Click Test Connection. The page makes a server-side client_credentials call to Meta to verify the App ID and Secret are valid. The result is shown immediately; a failure message explains what to fix (usually wrong credentials or an unreachable API).

Step 5 — Read the health card#

The health card lists six checks:

Treat any non-green row as a client-facing risk: connections can still "look" successful while leads silently stop arriving.

Expected result#

"Test Connection" succeeds, the redirect URI is saved in the Meta App, and a fresh client can connect their Facebook account through the guided setup without ever seeing an App ID or Secret.

Common mistakes#

• Entering the App Secret on the client side. Not possible by design — if a client asks, tell them the platform owns the app.
• Switching to Production too early. Lead permissions must be approved by Meta's App Review first.
• Forgetting the redirect URI. Without it, client connections fail at the callback.
• Re-saving the form and expecting the secret to show. It never echoes back; blank keeps the stored value.
• Using one Meta app per client. Per-connection credentials exist as a fallback, but the standard is the shared platform app.

Troubleshooting#

Technical details#

• Page: App\Filament\SuperAdmin\Pages\MetaDeveloperSettings (slug meta-developer-settings, Settings cluster, group System).
• Settings class: App\Settings\MetaSettings, group meta_platform — app_name, app_id, app_secret (encrypted, never echoed), environment.
• Fallback rule: tenant connections without their own credentials use the platform values (OAuthConnectionController + MetaConnector); per-connection app credentials remain supported.
• Redirect URI: route('oauth.callback', ['source' => 'meta']) → GET /oauth/meta/callback.
• Health card: healthChecks() rows — App Configuration, OAuth Callback, Domain, API Connectivity, Webhook, Permissions.
• Health job: leadhub:meta-health runs every 6 hours; leadhub:meta-ops-scan every 30 minutes.

Related guides#

• OAuth & permissions
• Meta lead capture pipeline
• System, SMTP & integrations
• Meta won't connect
• Marketing / Meta overview