Facebook Leads Setting

Facebook Leads Setting connects Meta lead ads to SquareOS People and CRM so campaign leads become duplicate-safe prospects with source, channel, form, owner, and follow-up task context.

What this page is for

Facebook Leads Setting connects Meta lead ads to SquareOS People and CRM so campaign leads become duplicate-safe prospects with source, channel, form, owner, and follow-up task context.

Who should use it

Owner, sales lead, marketing admin, platform admin

Where to find it

/admin/facebook-integration

Before you start

In Meta Business/Developers, confirm the business, Facebook Page, ad account, lead form, app, webhook callback, and permissions are owned or authorized for the gym.
Meta lead retrieval requires a Page access token or approved permissions for the Page/form. Use a long-lived page/system token path approved by the platform team.
Subscribe the app webhook to leadgen changes for the Page so SquareOS receives real-time lead notifications, then use the lead ID to retrieve full lead data.
In Meta Lead Ads testing, submit a test lead for each mapped form and confirm the webhook delivers a leadgen event before marking the campaign live.
In SquareOS Channel Account, choose Facebook leads, provider Facebook Leads, Account name, External account id for Page/Form/App reference, and credential/token reference for the Page/system token.
Facebook Leads channel fields are Facebook Page ID, Facebook Form ID, Meta App ID, Lead webhook verify token, Meta app secret / secret reference, Page access token / secret reference, Lead source name, Lead channel name, Owner staff user ID, Duplicate policy, Full name field, Email field, and Phone field.
In SquareOS, configure provider Facebook Leads, account/page/form identifiers, token credential reference, lead source, lead channel, owner mapping, duplicate policy, field mapping, and webhook status.
Every imported Facebook lead must run duplicate matching by phone/email before creating a new person.
Current backend contract: GET /engagement/facebook-leads/webhook verifies the Meta challenge against the configured verify token, POST /engagement/facebook-leads/webhook validates x-hub-signature-256 with the configured app secret, fetches leadgen_id details from Meta Graph API using the Page access token, maps common form fields, then hands off to the duplicate-safe Facebook lead intake. POST /engagement/facebook-leads/intake remains available for normalized/manual provider imports.
Production proof still requires a real Meta test lead for every mapped Page/form, visible webhook status VERIFIED, a created person/opportunity/follow-up task, and preserved page/form/ad/campaign metadata in the Facebook lead event payload.

Daily workflow

Open Admin, Facebook Leads, configure the channel account and map each Meta form to a SquareOS lead source/channel, default sales owner, duplicate policy, and field_data names for full name, email, and phone.
Submit a Meta lead test, confirm Facebook lead event is received, and verify the person/opportunity/task appears in People and Opportunity Board.
After launch, monitor failed lead events and unmapped form warnings before assuming campaigns are working.

Watch out

Do not map all forms to the same generic source if the gym needs campaign ROI. Preserve page, form, campaign, and ad metadata wherever the API provides it.

Use the left menu to open related pages in Integrations.
Use Ask Docs for questions that are already covered in this public documentation.