Kraya-AI Docs
Integrations

Meta Lead Ads

Capture Facebook Lead Ad Form submissions directly into Kraya.

{"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-10-12"}

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

  1. Generate configuration
    Under Webhook Configuration, click Generate Configuration to create your org’s webhook URL and secret. These values are reused across all Pages you attach.

  2. Verify webhook on Meta
    In your Meta app, use:

    • Verification URL: the Webhook URL shown on Kraya's Meta Lead Ad Forms page after Generate Configuration — copy it exactly. It ends in a random code unique to your account (…/api/webhooks/meta-lead-ad-forms/<random-code>), not your organization slug.
    • Verify Token: your generated secret

  3. Add your app and Pages
    In the Facebook Apps section, click Add App. All five fields are required for each Page you run lead ads from:

    • App ID (from your Meta app)
    • App Secret (from your Meta app)
    • Page ID
    • Long-lived Page Access Token (masked)
    • Default Country Code (for phone normalization)

    Click Add App to save. Repeat for each additional Page — there is no limit, and every Page reuses the same webhook URL and secret. Saved rows show as App ID: <id> with Edit and delete icons.

  4. (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.

Failure alert emails

Failed lead email alerts is a switch on the Meta Lead Ad Forms page (admin-only). Turn it on and Kraya emails everyone in your organization whenever a lead submission fails for a reason you can fix, with the subject "[Kraya] Action required: some Meta leads didn't reach Kraya".

Three situations trigger an alert, and each email names the affected Page IDs, how many leads were lost, and the exact fix:

  • An expired or invalid Page access token — generate a new token for that Page in Meta, then open the Page in Kraya, click Edit, paste the new token and save. The email also reminds you to check that your Facebook user still has leads access in Meta Business Suite → Leads Access Manager.
  • A Facebook Page sending leads that isn't added in Kraya — add the Page with its App ID, App Secret, Page ID and access token.
  • An incomplete setup — the webhook has not been generated, so re-add your Page and update the webhook URL in your Meta app if it changed.

Every email links straight to the Meta Lead Ad Forms page and tells you where to recover what was missed: Meta Business Suite → Leads Center, which holds the submissions Kraya never received.

Things worth knowing

  • You get one email per failed lead until the problem is fixed, so a broken token on a busy Page is noisy by design.
  • Problems only Kraya can fix — malformed webhooks, internal errors, a missing pipeline or stage — never generate a client email. Those stay with the Kraya team.
  • Emails go to every user in the organization who has an email address on file.
  • The switch is off until an admin turns it on, and the current state is shown on the Meta Lead Ad Forms page.

Lead source attributes (form name and form ID)

Kraya can record which Meta form produced each lead in two custom attributes, so you can filter, segment, and route by form:

  • 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:

  • These attributes are not created automatically. Kraya fills them only if your account already has custom attributes with exactly these keys. Add them first under Manage Attributes (open any lead → Edit → + Manage Attributes → + Add New Attribute), using the keys meta_lead_form and meta_lead_form_id.
  • Once the attributes exist, new leads ingested via Meta Lead Ads get them filled on creation. Leads that arrived before you added the attributes stay empty.
  • 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

Screenshots (to add later)

Google Sheets

Sync leads to Google Sheets and trigger automations based on sheet updates.

IndiaMART

Auto-create leads in Kraya from IndiaMART product inquiries via Push API.

On this page

Meta Lead Ad FormsOverviewSetupDay-to-day usageFailure alert emailsLead source attributes (form name and form ID)Edge cases to expectTroubleshooting (quick)FAQsRelated guidesScreenshots (to add later)