Skip to content

Connecting Facebook and Instagram lead ads

Leads from your Facebook and Instagram lead forms can arrive in the CRM the moment they are submitted, together with the campaign, ad and form they came from. You use your own Meta app and Facebook Page, so your leads never pass through anybody else's account.

Before you start

  • You need the tenant.integrations.manage permission (Owner or Administrator).
  • On Facebook you need a Meta app you control (developers.facebook.com), and the Advertise task on the Page that runs your lead ads.
  • Meta has to approve the app for the permissions below before it will send real leads. While the app is in Development mode, Facebook only sends leads from people who have a role in the app.

Steps

1. Collect three things from Meta

  1. Facebook Page ID. Find it on the Page under About → Page transparency, or in Meta Business Suite → Settings → Business assets.
  2. A Page access token. Create it in Graph API Explorer with these permissions: leads_retrieval, pages_show_list, pages_read_engagement and pages_manage_metadata. Your own user token also works. The CRM swaps it for a Page token that does not expire.
  3. Your Meta app secret. Find it in your app under Settings → Basic → App secret.

2. Connect

  1. Go to Integrations → Lead sources → Meta Lead Ads.
  2. Under 1. Connect your Facebook Page, enter the Page ID, the token and the app secret.
  3. Click Connect, or Save and verify if you are changing details.

The CRM checks the details with Facebook straight away. The Status card then says Connected, or tells you exactly what Facebook refused.

The token and app secret are stored encrypted and never shown again. To keep a saved value, leave its box blank when you save.

3. Check instant delivery

When the connection is verified, the CRM subscribes your Page to your app and points the app's webhook at your workspace. Card 2. Instant delivery shows On when this worked.

If it shows Off — leads arrive every 15 minutes, it lists what went wrong. Leads still arrive, because the CRM checks for new ones every 15 minutes, but not instantly. To set the webhook up by hand, open Webhook details, and setting it up by hand and follow the steps there.

Finally, switch your Meta app to Live mode.

4. Map each form's questions

Card 3. Lead forms and their fields lists every lead form on your Page. Open each one with Map fields and choose where each question goes. See Matching Facebook form questions to CRM fields.

5. Test

Send a test lead with Meta's Lead Ads Testing Tool. It should appear under Recent leads from Meta within a minute.

What this affects elsewhere

  • Each lead's source is Meta Ads, and the timeline says which Facebook form it came from.
  • The campaign, ad set, ad and form IDs are kept with the lead for reporting.
  • If you also use ad conversions, a lead from a Facebook form is matched back to that form submission in Meta.
  • People who can manage integrations get a notification when a form needs mapping, and a week before a token runs out.

What you cannot change later

Changing the Page starts the form list again. If you connect a different Page, the old Page's forms and their mappings are removed. Leads that already arrived stay in the CRM.

Issuing a new webhook address stops instant delivery until you paste the new address and verify token into your Meta app. The CRM asks you to confirm first.

If it does not work

What you see What it means What to do
Token rejected Facebook refused the token, or it belongs to a different Page Create a new token for this Page and save it
Permission missing The token lacks one of the four permissions Create the token again with all four ticked
Facebook unreachable Facebook did not answer this time Wait and click Save and verify again. Do not change a token that was working
Test lead never arrives The app is still in Development mode, or delivery is off See Facebook leads are not arriving
A form shows Questions unavailable The token cannot read that form's questions Create the token with leads_retrieval and pages_manage_metadata, save it, then Refresh forms

Last checked against the product on 2026-11-07. Needs the tenant.integrations.manage permission.