Meta Lead Ads

{"feature":"meta-lead-ad-forms","audience":"end_users","apps":["NextJS","Laravel"],"tags":["facebook","leads","webhooks","integrations","lead-import","import","meta-lead-form","custom-attributes"],"last_updated":"2026-05-31"}

Meta Lead Ad Forms

Meta Lead Ad Forms is one of the lead-import integrations in Kraya — alongside IndiaMART, JustDial, NeoDove, TagMango, MyOperator, Zoho, Google Sheets, the Connect Kraya API, and the Dashboard CSV/XLSX importer. Use this when you run Lead Ad campaigns on Facebook or Instagram and want each form submission to land in Kraya automatically.

Where in Kraya
- Page: https://kraya-ai.com/dashboard/meta-lead-ad-forms (Admin-only)
What it does
- Imports Facebook (Meta) Lead Ad Form submissions directly into Kraya as leads (one-way ingest from Meta to Kraya).
- Supports multiple Pages per organization, each with its own Page Access Token.
- Optional column mapping to align incoming form fields to Kraya (name, phone, email, notes, and custom attributes).

Overview

Generate a single webhook URL and secret for your org. Register the webhook in your Meta app and add your Facebook Pages with their long-lived Page Access Tokens. When a lead submits a form, Kraya fetches the full leadgen data and upserts the lead into your default pipeline at the New Lead stage.

Setup

Generate configuration
Click “Generate” to create your org’s webhook URL and secret. These values are reused across all Pages you attach.
Verify webhook on Meta
In your Meta app, use:
- Verification URL: https://kraya-ai.com/api/webhooks/meta-lead-ad-forms/{your-org-slug}
- Verify Token: your generated secret
Add your Pages
For each Page you run lead ads from, add:
- Page ID
- Long-lived Page Access Token (masked)
- Default Country Code (for phone normalization)
(Optional) Column mapping
Use “Column Mapping” to match form fields to Kraya’s lead fields and custom attributes.

Notes

Keep Page tokens up-to-date; if a token expires, leads from that Page won’t ingest until you update it.
One webhook URL/secret per org; multiple Pages can share it.

Day-to-day usage

Run your Lead Ads as usual. New submissions appear in Kraya shortly after they happen.
If you change your form fields, revisit Column Mapping to keep them aligned.

Auto-tagged lead source attributes

Every lead created from a Meta Lead Ad webhook is automatically tagged with two custom attributes so you can filter, segment, and route by the form that produced the lead:

meta_lead_form — the human-readable form name (e.g. "Summer Sale Sign-up")
meta_lead_form_id — the Meta-issued form ID (useful when two forms share the same name)

Behavior:

Both attributes are created automatically in your attribute schema the first time a Meta Lead Ad webhook hits your org. You don't need to add them by hand.
New leads ingested via Meta Lead Ads get both attributes populated on creation.
Existing leads receiving a fresh Meta Lead Ad submission only have these attributes populated if they were previously empty — Kraya never overwrites a value you have already set.
The AI extraction pipeline (used by AI Qualification and conversation summaries) is blocked from changing these values, so the integration-owned form attribution is preserved even if a lead is later re-qualified.
Use these attributes in filters (e.g. "all leads from the Summer Sale form"), Smart Triggers, sequence routing, or as merge-tag placeholders in Quick Replies and fixed bump-up messages.

Edge cases to expect

Webhook verification failing
- Re-check the exact Verify Token and the full verification URL.
Expired Page Access Token
- Update the token on the Meta Lead Ad Forms page. New leads start flowing again.
Missing phone/email in the form
- Kraya still creates the lead with available fields; you can complete the lead later.
High lead volume
- Events are queued briefly and processed; allow a few minutes during peak times.

Troubleshooting (quick)

“No leads appearing”
- Confirm the webhook is verified in Meta and that your Page token is current. Try a fresh test submission.
“Some fields not mapped”
- Update Column Mapping to reflect any new/renamed form fields.

Short decision tree

Nothing arriving → Verify webhook in Meta → Check/refresh Page token → Submit a test → Search by phone/email in Kraya.
Incorrect fields → Review Column Mapping → Submit a test again.

FAQs

Can I use multiple Pages?
- Yes. Add each Page with its own token. They share your org’s webhook URL and secret.
Do I need to re-generate the org webhook for a new Page?
- No. Use the same org URL/secret and just add the new Page.

Leads (creating, editing, searching)
Webhooks (Org outbound)
Google Sheets Integration