Urdhva Tech

Meta Leads for SuiteCRM - Admin Setup Guide | Facebook & Instagram Lead Ads

    Home → Meta Leads for SuiteCRM - Admin Setup Guide | Facebook & Instagram Lead Ads

Meta Leads for SuiteCRM

Admin Guide — Create the Meta app & configure SuiteCRM

Create the Meta app, connect Admin → Meta Leads in SuiteCRM, enable forms, and verify Facebook and Instagram leads. Screenshots match the real Meta and SuiteCRM screens.

Also see the product page: Meta Leads for SuiteCRM and the guide Sync Facebook & Instagram leads to SuiteCRM.

What you need

  • SuiteCRM with Meta Leads installed and a valid license
  • SuiteCRM Admin access
  • A Facebook user who can advertise on the Pages (and linked Instagram accounts) you want in CRM
  • A public HTTPS SuiteCRM URL — Meta cannot verify webhooks on localhost

1. SuiteCRM URLs (copy these)

You will paste these into Meta and into Admin → Meta Leads.

SuiteCRM fieldValue
OAuth Redirect URI https://your-crm.example.com/index.php?entryPoint=ut_sm_oauth_handler
Callback URL (Webhook URL) https://your-crm.example.com/index.php?entryPoint=ut_sm_inbound
Verify Token Any secret you choose (for example SuiteCRM_MetaLeads_2026). Letters, numbers, . _ - only. Same value in Meta and SuiteCRM.

2. Create the Meta app

  1. Open developers.facebook.com/apps → Create app.
  2. Select only this use case: Capture & manage ad leads with Marketing API.
  3. Enter an app name and contact email. Connect a Business Portfolio if asked. Create the app.
Meta Create app screen with Capture and manage ad leads with Marketing API selected
Meta adds Facebook Login for Business and Webhooks from that use case. Do not add other use cases (Page management, create ads, measure ads, consumer Login).

Permissions & features

Open Use cases → Capture & manage ad leads with Marketing API → Customize. You will see options such as Permissions & features and Webhooks.

Open Permissions & features:

  • Leave the permissions Meta already requires (including business_management, leads_retrieval, pages_*, ads_*). The trash icon on business_management is often grey — that is expected. You need it so Business Portfolio Pages appear in SuiteCRM.
  • Add optional permission pages_manage_metadata — SuiteCRM uses this to subscribe each Page to leadgen for real-time delivery.
  • Do not add email, catalog, messaging, or Page posting permissions.
Meta use case Customize Permissions and features with pages_manage_metadata added

OAuth redirect

  1. Open Facebook Login for Business → Settings.
  2. Enable Client / Web OAuth login if shown.
  3. Under Valid OAuth Redirect URIs, paste:
https://your-crm.example.com/index.php?entryPoint=ut_sm_oauth_handler
  1. Save.
Facebook Login for Business Valid OAuth Redirect URIs with SuiteCRM ut_sm_oauth_handler URL

Webhooks (Page → leadgen)

Order matters Save App ID, App Secret, Callback URL, and Verify Token in SuiteCRM first (step 3). Meta cannot verify the webhook until SuiteCRM already has the verify token.
  1. Go to Use cases → Capture & manage ad leads with Marketing API → Customize.
  2. Open Webhooks (same Customize screen as Permissions & features — not a separate product to add).
  3. Select object / product Page (not User, Instagram, or Ad Account).
  4. Set Callback URL:
https://your-crm.example.com/index.php?entryPoint=ut_sm_inbound
  1. Set Verify token to the same secret as in SuiteCRM.
  2. Click verify / subscribe so Meta can reach SuiteCRM.
  3. Subscribe to field leadgen only. Do not subscribe to feed, messages, or name.
Meta Use cases Customize Webhooks for Page with leadgen subscribed and SuiteCRM callback URL

App ID and App Secret

  1. App settings → Basic: copy App ID and App Secret.
  2. Set a Privacy Policy URL (needed before the app can go Live).
Meta App settings Basic showing App ID and App Secret fields

3. Configure SuiteCRM (Admin → Meta Leads)

  1. Open Admin → Meta Leads.
  2. Fill in and Save Settings:
    • Facebook App ID
    • Facebook App Secret
    • OAuth Redirect URI (must match Meta)
    • Callback URL (must match Meta)
    • Verify Token (must match Meta)
    • Reconciliation lookback hours (default 24, max 168) — how far back missed-lead recovery searches
  3. Then complete the Meta webhook verify step above if you have not already.
SuiteCRM Admin Meta Leads App Configuration form with App ID, Secret, Redirect URI, Callback URL, Verify Token

4. Authorize and check Connected Accounts

  1. Click Authorize with Facebook.
  2. Log in as the advertiser who owns the Pages. Grant the Lead Ads permissions (including business management) and allow every Page you need.
  3. Confirm status shows Connected.
  4. Under Connected Accounts, confirm Facebook Pages (and linked Instagram business accounts, if any) are listed.
SuiteCRM Meta Leads OAuth Authorization section showing Connected status
SuiteCRM Meta Leads Connected Accounts table with Facebook Pages and Instagram accounts
SuiteCRM requests: pages_show_list, leads_retrieval, pages_read_engagement, pages_manage_metadata, pages_manage_ads, business_management, ads_management, ads_read. Authorization also syncs page tokens and subscribes Pages to leadgen.
Missing Business Portfolio Pages? The authorizing user usually lacks access, or business_management was not granted. Fix access, then use Refresh tokens now or disconnect and authorize again.

5. Configure each account (forms, mapping, assignment)

For each Page or Instagram row, click Configure.

  1. Lead Assignment — Keep Empty, Specific User, Round Robin (pick users), or Security Group.
  2. Lead Forms — click Refresh Forms, then enable only the forms that should create SuiteCRM Leads. Forms that stay unchecked are ignored.
  3. Field Mapping — name, email, and phone usually map automatically. Map or set custom questions to Don’t import. Use Name (split to First / Last) when the form sends a full name.
  4. Click Save Configuration.
SuiteCRM Meta Leads Field Mapping table mapping Meta questions to Lead fields

6. Verify the setup

Cron (required)

SuiteCRM cron must be running. Meta Leads uses it for:

  • Token refresh (scheduler job is created on authorize)
  • Meta Lead Reconciliation — about every 30 minutes; catches leads missed by webhooks and retries failed imports
SuiteCRM Meta Leads Reconciliation section with Run Reconciliation Now and stats

Optional: on Admin → Meta Leads use Run Reconciliation Now if a webhook did not deliver (for example after a temporary outage).

7. Go Live (only if other customers’ Pages will connect)

In Development mode, only app Admins / Developers / Testers can connect. For other businesses:

  1. Complete Business Verification on the Meta Business Portfolio.
  2. Submit App Review for the Lead Ads permissions (include pages_manage_metadata).
  3. In review notes: how to open Admin → Meta Leads, Authorize, confirm Pages appear, enable a form, create a test lead.
  4. After approval, Publish the app. In SuiteCRM, Disconnect → Authorize again if needed.

Setup checklist

Meta

  • Use case: Capture & manage ad leads with Marketing API only
  • Added pages_manage_metadata
  • OAuth redirect URI matches SuiteCRM
  • Use cases → Customize → Webhooks → Page → leadgen; callback + verify token match SuiteCRM
  • Privacy Policy URL set (before Live)

SuiteCRM

  • License valid
  • Admin → Meta Leads: App ID, Secret, URIs, verify token saved
  • Authorize completed → status Connected
  • Expected Pages / Instagram accounts listed
  • Per account: forms enabled, mapping OK, assignment set, configuration saved
  • Cron running

If something fails — what to check

SymptomCheck
Webhook verify fails SuiteCRM saved first; callback URL and verify token identical; site reachable on HTTPS
Authorize works but no Pages User’s Page access; business_management granted; then Refresh tokens or re-authorize
Lead not in SuiteCRM Form enabled on that account; license valid; webhook subscribed to leadgen; try Run Reconciliation Now
Instagram leads missing IG business account linked to the Page; Instagram row configured and form enabled (not only the Facebook row)
Token expiry warning Click Refresh tokens now; confirm cron is active