Lead Chains — Facebook Lead Ads

A Lead Chain pipes leads from an ad platform straight into your CRM — no more downloading CSV exports from Ads Manager. This guide covers the Facebook (Meta) connector: connecting your account, picking the form, importing history, and how auto-sync keeps new leads flowing in.

Available to Admins. Find it under Settings → Lead Chains, or go to /chains.

The chains list

The Lead Chains page is a table of every chain, one row each:

  • Created On — when the chain was set up.
  • Chain Name — click it (or the ⋯ menu → Edit) to open the chain.
  • Source — the platform with a colored letter badge (f for Facebook Lead Ads, G for Google Lead Form Ads, and so on).
  • Destination — where the leads go (CRM Leads).
  • Leads — how many leads the chain has captured.
  • Created By — the teammate who set it up, with an avatar.
  • Status — a toggle switch: Active syncs, Paused stops it. Flip it right in the table.
  • Recent Lead Date — when the chain last delivered a lead; a quick health check at a glance.
  • ⋯ — Edit and Delete. Deleting a chain stops its form from syncing (existing leads stay).

Creating a chain

Click Create New Chain to open the three-step wizard:

  1. Connect your Apps — pick the source (Facebook Lead Ads) and the destination (Leads), plus tags and assignment.
  2. Field Mapping — match the form's questions to CRM lead columns.
  3. Review & Publish — confirm and enable.

Step 1 — Connect Facebook

Click Connect Facebook Account. You'll be sent to Facebook's consent screen; approving it brings you back with your account connected. The connection is stored per organization — teammates see the same connection, and Disconnect removes it for everyone.

Once connected, three searchable dropdowns appear (each has a search box at the top — start typing to filter long lists):

  • Choose your Ad Account — the ad account running the campaigns. The selection is saved with the chain, so reopening it later shows the same account.
  • Choose your Facebook Page — the page that owns the lead forms.
  • Facebook Form — the forms to capture. This is a multi-select: tick as many forms as you want in one chain — each selected form appears as a removable chip below the dropdown, and the button reads "2 forms selected". Leave it empty ("All forms on this page") to catch every form on the page, including future ones.

On the right, choose the destination Module (Leads), optional Segmentation tags applied to every captured lead, an Assignment rule to auto-assign new leads to a teammate, and whether to Allow duplicates (by default, a repeat submission from the same email/phone is logged on the existing lead instead of creating a new one).

Step 2 — Field Mapping

The wizard reads the forms' actual questions from Facebook and suggests mappings automatically (Full name → Name, Email → Email, and so on). Each row pairs a CRM column ("Leads >> Name", "Leads >> Email"…) with a dropdown of the form's questions; when several forms are selected, their questions are merged into one list. Adjust any mapping; Name is required. Unmapped questions still arrive — they're kept on the lead's timeline in the capture activity.

Map into custom fields: any custom fields you've defined for Leads under Settings → Custom Fields appear here too, as "Leads >> <your field>" rows — map a form question to one and the answer lands in that custom field on every captured lead (visible in the lead drawer, the leads table, and filters). The Search fields in the CRM box narrows the list when you have many fields.

Test Connection verifies the CRM can read your selected form with the connected account before you save. Finish with Save and Publish to go live, or Save as Paused to save without syncing yet.

Importing historical leads

The live sync only covers leads submitted after the chain exists — but your form probably collected leads before that. When editing a saved chain that has at least one form selected, an Import historical leads card appears under the form picker:

  1. Pick a window — Last 7 / 10 / 30 / 90 days, or Custom range with exact from/to dates.
  2. Click Import.
  3. The result shows what happened: "Found 13 leads — 3 imported, 10 already existed."

Imports are safe to repeat: a lead already in the CRM (matched by its Facebook lead ID, or by email/phone unless the chain allows duplicates) is skipped, never duplicated.

Auto-sync — how new leads arrive

Once a chain is published, new form submissions reach your Leads page through two independent paths:

  1. Real-time webhook — saving a chain subscribes the Facebook Page to the app's leadgen webhook, so Meta pushes each submission to the CRM the moment it happens.
  2. Background sync (every 5 minutes) — the server also polls every enabled chain's form for new submissions. Even if the webhook is ever misconfigured or delayed, leads still land within 5 minutes.

Both paths run through the same pipeline: field mapping, duplicate detection, tagging, and auto-assignment — so it doesn't matter which one delivers a lead first; the other will recognize it and skip it.

Rate-limit handling

Meta caps Graph API usage per hour and reports live usage on every response; the background sync is built to stay well under it:

  • Each organization's page list (and page tokens) is cached for 30 minutes instead of refetched every tick — pages rarely change.
  • A chain that hasn't seen a lead in 3+ days is checked every ~30 minutes instead of every 5 — active chains keep the fast cadence.
  • If Meta ever does throttle a request, the sync backs off for 30 minutes across every chain rather than retrying into the same wall. This shows up in the server log as [MetaSync] rate-limited by Meta — pausing all sync for 30 min.
  • Usage nearing the cap logs a warning ([Meta] app usage at N% of the rate limit) before it becomes a problem — worth watching if you connect many chains.

Every captured lead gets:

  • Source META_LEAD_ADS and a meta-ads tag (plus your chain's segmentation tags)
  • Campaign attribution — UTM Source/Medium set to the platform, UTM Campaign filled with the Meta campaign's name and UTM Content with the ad's name (falling back to the raw IDs when Meta doesn't return names). See them under Tracking & Attribution in the lead drawer, and filter or chart by them.
  • A timeline activity recording the form, campaign/ad IDs, and the raw answers
  • Values routed into any mapped custom fields
  • The chain's auto-assignment, if configured

Troubleshooting

"URL blocked" on Facebook's consent screen — the redirect URL isn't whitelisted. In Meta for Developers → your app → Facebook Login → Settings → Valid OAuth Redirect URIs, add https://<your-domain>/api/auth/callback/facebook style entries; for the chain wizard specifically, https://<your-domain>/api/auth/facebook/callback.

Ad Account list is empty but Pages work — the ads_management permission wasn't granted. While the Meta app is in Development Mode, only Facebook accounts added as Admin/Developer/Tester on the app receive it; for everyone else the app needs Advanced Access via App Review. An error banner under the dropdown shows Facebook's exact response, with a Retry button.

"The connection has expired" — Facebook tokens last ~60 days. Click Connect Facebook Account again to refresh.

Leads stopped arriving — check the chain is still enabled on the Lead Chains list, and that the connection hasn't expired. The 5-minute sync logs each run on the server ([MetaSync]), which an administrator can check.