Zodiac Tech CRM Docs

Connect Meta (Facebook)

Wizard step 3 — connect your Facebook Page to the CRM safely with OAuth. You never share your Facebook password, and you can revoke access any time.

client admin Easy ⏱ 5 min Updated 2026-10-05

Connect Meta (Facebook)

This is wizard step 3: "Connect your Facebook account". Connecting lets the CRM read the lead forms on your Facebook Page and receive new leads the moment someone submits them. The connection uses Facebook's official login (OAuth) — your Facebook password is never entered into, seen by, or stored in the CRM.

The Connect Meta wizard step

Who this is for

  • Workspace owners and admins doing initial setup.
  • Admins re-connecting after a token expired or a password change.

Difficulty: Easy · Time: 3–5 minutes · Prerequisites:

  • A Facebook account that manages the Facebook Page you advertise with (usually a business admin of the Page).
  • Pop-up windows allowed for your CRM address (the Facebook login opens in a popup).
  • Your CRM is reachable over HTTPS in production — Meta only redirects back to secure addresses.

What the CRM asks Facebook for Four standard permissions: read your lead forms and leads (leads_retrieval), see your Pages (pages_show_list, pages_read_engagement), and manage ads for reporting (pages_manage_ads). Nothing is posted to Facebook on your behalf.

Step by step

1. Start the connection

  1. In the wizard step Connect your Facebook account, click Connect Facebook.

    • You can also do this outside the wizard: Settings → Connections → Lead Source Connections → Connect (one of the connection rows for Meta).

  2. What happens: a Facebook login window opens. Log in (if asked) and approve the permissions for the Page(s) you manage.

  3. Expected result: Facebook redirects back to your CRM and the connection row shows a connected state. In the wizard you should now see a checklist with four lines:

    Checklist line What it confirms
    Facebook Page The CRM can see your Page
    Instagram Whether an Instagram account is linked to the Page
    Ad Account The CRM can look up your ad accounts
    Lead Forms The CRM can read (or later fetch) forms on the Page

2. What happens next

  • If you manage one Page, the CRM selects it automatically and you continue straight to Choose your Page & Ad Account.
  • If you manage several Pages, the CRM asks you to choose one — that is wizard step 4, covered in Choose your Page & Ad Account.
  • If the CRM found no Pages at all, you get a warning and setup pauses here — see troubleshooting below.

3. Re-check or refresh the connection any time

  1. Go to Settings → Connections → Lead Source Connections.
  2. Use the row actions:
    • Test — pings Meta with your Page token. Success names the Page it reached; failure shows the error reason.
    • Refresh Pages — re-reads the Pages this Facebook account can currently manage (useful after you were added to a new Page, or a Page access was revoked).
    • Reconnect — runs the Facebook login again (use this if the connection needs re-authorization).
  3. Expected result: the row returns to a healthy state, and the wizard step completes.

Failure states and what they mean

What you see What happened What to do
"We couldn't finish connecting your Facebook account. Your Facebook session may have expired." The Facebook popup was left open too long, or the login session expired before approval Click Try Again in the step — it restarts the same OAuth flow
Returned to Lead Source Connections with a session expired message The CRM-side OAuth state was lost (browser restarted, cookie cleared) Start the connect flow again
State did not match error The callback did not match the login attempt the CRM started (e.g. two accounts, two tabs) Close other Facebook tabs and retry once
Authorization denied You declined the permission screen (or a Facebook Business admin must approve the app) Retry and accept the permissions; business-managed accounts may need their admin's approval
Token exchange failed Facebook refused to issue a token — often a Meta app configuration issue on the platform side Retry once; if it persists, contact Zodiac Tech support (this is a platform-level setting)
"No Facebook Pages found" warning The Facebook account does not manage any Page Log in with the account that is an admin of your business Page, then Reconnect

A "needs re-auth" connection blocks lead flow If your Meta token expires, is revoked, or your Facebook password changes, the wizard marks the Meta step BLOCKED and Zodiac Tech's dashboard flags the workspace. Until it is re-connected, leads will not arrive. Reconnect from the row's action or click Try Again in the step.

Expected result

  • Your Meta connection exists on the workspace, shows a healthy status, and the wizard step is done (or moves you to Page selection).
  • The Platform team can see the connection status from the Super Admin dashboard if anything later breaks.

Common mistakes

  • Logging in with a personal Facebook account. Use the account that manages the business Page — otherwise no Pages or lead forms appear.
  • Denying one of the permissions. Meta connect needs all four to read forms and leads; a partial approval fails the flow.
  • Blocking pop-ups. The Facebook login opens in a popup; allow pop-ups for the CRM address.
  • Assuming the CRM now "posts" ads. Connecting does not start or change any advertising; it only reads assets and receives leads.
  • Clicking Connect twice. One connection per workspace is enough; use Reconnect/Refresh on the existing row instead.

Troubleshooting

Symptom Likely cause Fix
Connect button opens nothing Popup blocked Allow pop-ups, then click Connect Facebook again
Redirected but no connection row appears OAuth callback failed before storage Check the page's error banner (session/denied/token messages above) and retry
Test action fails with a token error Stored token expired or revoked Reconnect (or Try Again in the wizard)
Page you expected is missing later You were added to the Page after connecting Refresh Pages, then re-select your Page
Connection OK but no leads arrive Separate issue — the form may not be ticked See Meta won't connect and How a Meta lead becomes a CRM lead

Not the only place to connect The wizard step and Settings → Connections → Lead Source Connections drive the same connection. There is no second, hidden connection to maintain.

Technical details

  • Flow: App\Http\Controllers\OAuthConnectionController (oauth.redirect route). The OAuth state is stored in the session and compared with hash_equals on the callback.
  • Stored on the lead_source_connections row: user_access_token, token_expires_at, and available_pages (each entry {id, name, access_token}).
  • One Page → auto-select; several Pages → page_id stays empty until you pick one (row action Select Page); no Pages → warning notification.
  • Freshness: leadhub:meta-health pings connections every 6 hours; failed health moves the connection to an error/needs-reauth state, which surfaces as a BLOCKED wizard step.
  • Test action: MetaConnector::testConnection() — verifies the stored Page token against /{page_id} (or /me when no Page is chosen) and records the last test result on the row.

Was this page helpful?