Facebook Instant Forms

A Facebook Instant Form is a lead form that lives inside Meta's ad platform - you build it in Ads Manager, and it opens without ever leaving Facebook or Instagram. Formwork does not build those forms. It connects to one you already have and takes the leads as they come in.

The work therefore splits differently to a website form. There is no builder. Instead there is one step nobody can do for you: telling Formwork which of Meta's field names mean which of yours.

What actually happens when a lead comes in

Worth understanding before anything goes wrong, because it explains most of the surprising behaviour.

Meta's webhook does not contain the lead. It contains an ID and nothing else. Formwork then calls Meta back with the Page's access token to fetch the answers. That is why the integration has to keep working - a broken token means leads that arrive as notifications Formwork cannot open.

The subscription is per Page, not per form. Connecting one lead form subscribes Formwork to the whole Page. Connecting a second form on the same Page is just a second row in Formwork; it does not change anything at Meta's end.

Missed webhooks are swept up. A reconciliation job runs on a schedule and asks Meta for recent leads Formwork has not seen, so a webhook lost to a deploy or an outage still arrives - late, but it arrives.

Step 1 - Connect your Facebook account

Go to Forms → New capture and choose Facebook Instant Form.

Press connect. The Facebook authorisation dialog opens in a new tab, deliberately - redirecting away would throw away the wizard you are halfway through. Approve the permissions, come back to the Formwork tab, and press Refresh accounts.

Step 2 - Pick a Page, then a form

Choose the Page the ad runs from, then the lead form itself. Forms already connected to Formwork are marked, so you cannot create a duplicate by accident.

Step 3 - Attach a routing setup

Same step as any other capture: pick which routing rules these leads should run through, or skip it and decide later.

If the routing setup expects fields this form does not collect, Formwork tells you as you attach it. That warning is worth reading - it is the difference between finding out now and finding out from a destination's rejection rate next week.

Step 4 - Match up the fields

This is the step that matters. Open the form from the Forms list to reach its settings page.

The left column lists everything found in an actual lead from this form. The right side is where you say what each one means.

Press "Do it for me" first. It matches everything it recognises by name and saves you most of the typing. Then check its work and fill in the rest - the badges in the toolbar tell you how much is still unmapped.

For each row you can also set:

• Clean-up steps - an ordered chain applied before the value is stored. Trim whitespace, take the first answer from a list, format a phone number into E.164, turn "Texas" into "TX". The order matters and is shown as numbered chips.
• Kind of value - what the answer should be coerced into. Following the canonical field's own type is almost always right.
• Required - reject the lead entirely if this answer is missing.

Meta's test leads look broken. They are not.

Meta's testing tool sends placeholder strings like <test lead: dummy data for phone_number>. Those cannot be turned into a real phone number, so the preview says so in amber and tells you a real lead will convert fine. That is the expected result on a correctly configured form, and it is not an error.

Step 5 - Confirm it works end to end

Send a test lead through Meta's Lead Ads Testing Tool, then open Logs. The lead should appear in Lead logs within a few seconds, with your mapped fields on the left of the drawer and Meta's raw payload on the right.

Compare the two. If a value is missing from the normalised side, the mapping for that field is wrong

• the raw payload will show you the field name it actually arrived under.

Keeping it working

Tokens expire, and grants get revoked. A scheduled job refreshes Page tokens before they lapse, so the ordinary case is silent. When a refresh cannot succeed the integration is flagged and needs reauthorising. Integrations covers what breaks it and how to reconnect.

Changing the form at Meta's end changes the field names. Adding or renaming a question in Ads Manager will produce leads with paths your mapping does not know about. Pull a fresh lead and check the mapping after any change to the form.

What to read next

• Integrations - keeping the Meta grant this all depends on alive.
• Fields - what the canonical keys on the right of the mapping editor are.
• Routing - the routing these leads run through.
• Destinations - where these leads end up.