Before you begin

  • Confirm the Facebook Page or Instagram account is connected to the ad account.
  • Confirm your Meta app or bridge has access to the Page and the required lead retrieval permissions.
  • Add the correct privacy policy and consent language to every instant form.
  • Decide whether your implementation will post normalized lead fields directly to InstaChime or only send a lead ID that a bridge resolves through Graph API.

Meta setup

  • Create or open your Meta developer app.
  • Configure a leadgen webhook subscription for the Page object through the Meta app or through your bridge.
  • Subscribe the app to the relevant Page leadgen events.
  • Map the returned form fields to name, email, phone, campaign, form ID, and lead ID.
  • POST the normalized result to `https://instachime.com/api/webhooks/capture` with `x-instachime-secret`.

Bridge payload example

{
  "source": "meta_lead_ads",
  "source_platform": "facebook",
  "form_id": "1234567890",
  "leadgen_id": "9876543210",
  "full_name": "Taylor Brooks",
  "email": "taylor@example.com",
  "phone": "+15555550123",
  "campaign_name": "Spring demo campaign",
  "ad_id": "23800000000000000"
}

Verify

  • Generate a test lead from Meta tools or a controlled instant form submission.
  • Confirm the bridge receives the `leadgen_id` and resolves the full lead fields.
  • Confirm the InstaChime lead contains the Meta form ID, lead ID, and campaign/ad context.
  • Confirm alerts and CRM webhooks fire from the created lead.
  • Confirm your bridge handles duplicate lead IDs without creating duplicate operational leads.

Exact Meta setup path

  • Create the instant form in Meta Ads Manager and attach it to the Facebook Page or Instagram account used by the ad.
  • In Meta Developer settings, create or open the app that will receive leadgen notifications.
  • Add the Webhooks product to the app.
  • Subscribe the app to the Page `leadgen` field.
  • Generate or configure a Page access token with the permissions required by Meta for lead retrieval.
  • Subscribe the app to the Page that owns the lead form.
  • When Meta sends a leadgen notification, use the lead ID to retrieve the full lead fields through the Graph API.
  • POST the normalized result to `https://instachime.com/api/webhooks/capture` with `x-instachime-secret`.

Bridge requirements

  • Persist the Meta `leadgen_id`, `form_id`, Page ID, ad ID, ad set ID, and campaign ID when available.
  • Retrieve `field_data` from Meta and map each returned field name to an InstaChime field.
  • Store custom disclaimer responses and consent responses if the form uses them.
  • Backfill leads from Meta if your bridge was offline or token refresh failed.
  • Log Graph API errors with the lead ID so the exact failed lead can be retried.

Meta field mapping

  • `full_name`, `first_name`, `last_name` -> InstaChime name fields.
  • `email` -> `email`.
  • `phone_number` or phone custom field -> `phone`.
  • `company_name` -> `company`.
  • `job_title` -> `job_title`.
  • Form questions such as budget, service, property type, or preferred time -> raw fields and optionally `message`.

Meta troubleshooting

  • If the webhook fires but no contact data reaches InstaChime, the bridge is probably forwarding only the notification instead of retrieving the full lead.
  • If Meta test leads are not visible, confirm the app is subscribed to the correct Page and form.
  • If retrieval fails, refresh the Page access token and check that the app has the required permissions.
  • If duplicate contacts appear, dedupe on `leadgen_id` and keep email/phone dedupe as a fallback.
  • If old form fields appear, confirm the active ad uses the edited form version.

Official references

These vendor-owned pages explain the controls and requirements referenced in this guide.