OAuth & permissions#

Connecting Meta is a permission handshake: Facebook asks "do you allow this app to see and manage these assets?", you approve, and the CRM receives an access token it uses to fetch leads and run ads. This page explains what you are granting, how to complete the connection, and what to do when it expires or misbehaves.

Who this is for#

• Admins — perform the connection.

• Business owners — understand what you are approving.

• Support — diagnose "Meta won't connect" situations.

• Difficulty: Medium

• Time: 12 minutes

• Prerequisites: You are an admin of the CRM workspace. Your Facebook account must be an admin of the Page you want to connect (and have access to the ad account).

What you grant (the permissions, in plain language)#

When you connect Meta (Facebook), the app asks for these permissions:

Connecting Instagram asks for instagram_basic, instagram_manage_messages, and pages_show_list.

Steps#

1. Start the connection#

1. Go to Settings → Connections (/admin/lead-source-connections).
2. Find the Meta source row and click Connect (the OAuth action).

Expected result: you are redirected to Facebook's login/consent screen.

2. Approve the permissions#

1. Sign in to the Facebook account that manages the Page.
2. Review the permissions (table above). If Facebook shows a "Business login" or Page-selection step, pick the Page(s).
3. Click Continue / Allow.

Expected result: Facebook returns you to the CRM. The connection is created.

3. Choose the Page (and ad account)#

After the redirect, the CRM looks up your Pages (/me/accounts):

• One Page found — it is selected automatically.
• Several Pages, none chosen — the connection notifies you to use the Select Page action, and the row lists the available Pages.
• No Pages found — the connection warns that re-authorisation is needed (this usually means your Facebook account lacks Page admin rights).

1. On the connection row, use Select Page and choose from the pages found.
2. If you need a fresh list (new Page, changed access), use Refresh Pages then select again.

Expected result: the connection shows the chosen Page. Lead forms on that Page can now be selected in the CRM.

4. Test the connection#

1. Use the Test action on the connection row.

Expected result: the CRM verifies the token against Meta and reports success (or the exact failure). The platform also pings every connection automatically — leadhub:meta-health runs every 6 hours.

5. Keep it alive#

Meta access tokens are long-lived but not eternal (commonly around 60 days). When a token expires, leads stop arriving and the connection turns unhealthy.

1. Watch for the integration sync failed notification or a red status on the connection / Ads health page.
2. Re-run Connect and approve again.

Expected result: the connection is healthy again and missed lead-form submissions can be re-fetched from Meta (webhook redelivery), so a short outage usually does not lose leads.

Expected result#

A healthy, tested Meta connection that only sees the Page you chose — with a clear paper trail of when you connected, and clear signals when re-authorisation is due.

Common mistakes#

• Connecting with a personal account that is not a Page admin. Select Page will never be offered — sort the Facebook access first.
• Connecting the wrong Page. Leads from a different brand start arriving. Reconnect and select correctly; past leads can be filtered by source.
• Approving without reading the Page picker. If you skip the selection, the connection stays in "select a page" state and no leads flow.
• Ignoring expiry notifications. Leads quietly stop; the health scanner flags it, but only if someone reads it.
• Sharing credentials in chat. Never needed — OAuth means no passwords or secrets are ever typed into the CRM by clients.

Troubleshooting#

Technical details#

• Platform app settings: App\Settings\MetaSettings (app id, encrypted app secret, environment development|production) — edited in Super Admin → Settings → Meta Developer. Per-connection credentials exist for backwards compatibility only.
• Flow: App\Http\Controllers\OAuthConnectionController — redirect() stores oauth_state_{source} + oauth_connection_id in the session; the callback validates state with hash_equals; metaExchange() exchanges the code at graph.facebook.com/{version}/oauth/access_token using the connection's or platform's credentials (typical expires_in 5184000 s ≈ 60 days), then fetches /me/accounts into credentials.available_pages.
• Notifications emitted: no pages (warning — re-authorise), multiple pages with no selection (prompt to Select Page), single page (auto-picked).
• Connection screen: App\Filament\Resources\LeadSourceConnectionResource with actions Connect, Test, Select Page (from credentials.available_pages), Refresh Pages.
• Health: leadhub:meta-health (6-hourly) plus the ops scanner for dead connections.

Related guides#

• Meta overview — the big picture.
• Meta lead capture pipeline — what happens after the connection.
• Meta won't connect — symptom-based fixes.
• Ads health & needs attention — how the platform watches connections.