A8gent
Build guide - Meta lead ads + SMS

Facebook lead ads to SMS, in under a minute

Meta's leadgen webhook sends an ID, not a lead. Here is the Graph API retrieval, the permissions and 90-day limit, consent wording, and the first-minute text.

A8gent
·

What you get from this guide

  • Exactly what Meta's leadgen webhook delivers - and what it does not
  • The Graph API call that turns a leadgen_id into a phone number
  • The permissions, Page subscription and 90-day limit Meta documents
  • Consent language and what Twilio requires in the first message
  • A first-minute-to-day-seven sequence, and where the human takes over

Why the delay is the whole problem

A Facebook lead ad works by removing effort. The form is pre-filled, it opens inside the app, and the person taps submit in about four seconds while doing something else. That is why lead ads are cheap. It is also precisely why the lead is fragile: the person did not go to your website, did not read your reviews, and in many cases will not remember your business name an hour later. They tapped a button on an ad in a feed.

So the currency here is not lead volume, it is elapsed time. A lead that sits in Ads Manager until somebody exports a CSV on Thursday is not a warm lead that got a bit cooler - it is a stranger receiving a cold call about a form they have forgotten filling in. Everything on this page exists to compress that gap to under a minute.

We are not going to put a made-up conversion percentage next to that claim. The mechanism is enough: the person is holding their phone right now, has context right now, and is very likely filling in two or three of these forms in the same sitting. First reply gets the conversation. That is the thesis of speed-to-lead, and it is why lead response time is worth measuring as its own number rather than folding it into a conversion rate.

Every Meta and Twilio fact below is dated August 2026 and taken from the vendor's own documentation, and where a page would not render for us to read it, we say so rather than paraphrasing something we did not see.

What the leadgen webhook actually sends

Here is the fact that breaks most first attempts, and the reason the aggregator posts on this query are so thin. The webhook does not contain the lead.

Meta's lead ads webhooks documentation shows the notification carrying a leadgen field whose value contains leadgen_id, page_id, form_id, adgroup_id, ad_id and created_time. No name, no email, no phone number. The documentation states it directly: you use the leadgen_id from the notification to retrieve the data associated with the lead.

The leadgen notification value (shape per Meta's docs, August 2026)

"field": "leadgen",
"value": {
  "leadgen_id": <id>,
  "page_id":    <id>,
  "form_id":    <id>,
  "adgroup_id": <id>,
  "ad_id":      <id>,
  "created_time": <timestamp>
}

# Notice what is absent: the answers.
# This is a doorbell, not a delivery.

Two setup steps sit behind that notification, and skipping either produces the same symptom - a form that submits successfully and an endpoint that never fires:

  • Subscribe the Page object to the leadgen field. Meta's quickstart routes you through the standard Webhooks setup: create the endpoint, complete the verification handshake, then select the Page object and subscribe to the leadgen field.
  • Install the app on the Page. Meta documents a POST to the /subscribed_apps endpoint using a Page access token from someone with ADVERTISE permissions. This is the step people miss, because the Webhooks configuration screen looks complete without it.

Test the endpoint before you test the ad

Meta's Webhooks product includes a test-send facility, and the leadgen field can be exercised with a test lead from the form's preview tool. Use both before spending money on impressions. A workflow that has never received a real payload shape is a workflow you are debugging live, in front of paying traffic. If webhooks versus scheduled polling is a live question for you, the polling vs webhook entry covers the trade properly - for this use case webhooks win outright, because polling on a schedule reintroduces the exact delay the build exists to remove.

Retrieving the lead from the Graph API

With the ID in hand, one more call gets the answers. Meta documents retrieval as a request to the lead ID on the Graph API - https://graph.facebook.com/<version>/<LEAD_ID> with an access token - returning a field_data array of name and values containing the submitted information such as email and name.

Turning the ID into a lead (per Meta's retrieval docs, August 2026)

GET https://graph.facebook.com/v25.0/<LEAD_ID>
    ?access_token=<PAGE_OR_USER_TOKEN>

-> {
     "created_time": "...",
     "id": "<LEAD_ID>",
     "field_data": [
       { "name": "full_name",    "values": ["..."] },
       { "name": "phone_number", "values": ["..."] },
       { "name": "email",        "values": ["..."] }
     ]
   }

# field_data is an ARRAY, not an object.
# Map it by name. Never index by position -
# editing the form reorders it.

Three things to get right in this step, because each one causes a bug that only shows up in production:

  • Map by field name, never by array position. The instant form is editable in Ads Manager by anyone with access, and adding a question in the middle shifts every index after it. Position-based mapping is a workflow that silently starts texting people their own email address.
  • Normalise the phone number immediately. Pre-filled numbers arrive in whatever format the account holds. Convert to E.164 at the point of retrieval so every downstream node - SMS, CRM, deduplication - is comparing the same string.
  • Make the retrieval step idempotent. Meta may retry a delivery, so the same leadgen_id can arrive twice. Key on it and discard repeats. See idempotency for why this is the one piece of defensive design worth building on day one - a duplicate text to a new lead reads as a malfunction, which is the opposite of the impression the build exists to create.

Bulk reads exist as a backstop rather than a primary path. Meta documents reading leads by ad at /<AD_ID>/leads and by form at /<FORM_ID>/leads, noting that a form can be re-used for many ads and therefore accumulates more leads than any single ad. A once-daily bulk read makes a good reconciliation job: it catches anything the webhook dropped while your endpoint was down.

Permissions, retention and rate limits

Meta's two relevant pages list slightly different permission sets, which is worth stating plainly rather than tidying into one clean list.

Permissions Meta documents for lead ads integration (developers.facebook.com, August 2026)
Documented onPermissions listed
Retrieving leads guideleads_retrieval, pages_show_list, pages_manage_ads, pages_read_engagement
Webhooks integration quickstartleads_retrieval, pages_manage_metadata, pages_show_list, pages_read_engagement, ads_management
Page installPOST to /subscribed_apps with a Page token from a user with ADVERTISE permissions

Two limits shape the design more than any of the above. First, retention: Meta's Business Help Center describes lead information as available for 90 days, with older leads no longer downloadable. We could not render that help article to quote it verbatim - Meta's Business Help Center pages load client-side and returned only a page title to our fetch - so treat the 90-day number as Meta-sourced but confirm it yourself before relying on it. The developer documentation does independently reference a 90-day window: it calculates the retrieval rate limit as 200 multiplied by 24, multiplied by the number of leads created in the past 90 days for a Facebook Page.

Read that formula for what it implies rather than as a number. Your quota is proportional to your recent lead volume, so a brand-new form on a Page with no history has a small allowance. That is fine for one call per lead and unforgiving of a retry loop. It is another argument for handling each lead once, correctly, rather than polling aggressively.

Second, retention means Ads Manager is not your lead database. Every lead needs to land in something you control on the day it arrives - a CRM, a sheet, your own store. The pattern is the same one in the Housecall Pro to Google Sheets sync: write it down somewhere durable first, act on it second.

The sequence: first minute to day seven

A single instant text is most of the value. The rest of the sequence exists for the people who were driving, in a meeting, or genuinely undecided. Keep it short, stop it dead on any reply, and hand off to a person the moment there is something to talk about.

A lead ad follow-up sequence (illustrative - tune to your business)
WhenChannelJob of the message
Within 60 secondsSMSAcknowledge by name, reference the ad's offer, ask one question, include STOP
+5 minutes, no replyCallA human dials. The text has already introduced you, so this is not cold
+1 hour, no replyEmailThe detail the text could not carry: what you do, pricing shape, booking link
Next morningSMSOne short nudge, offering a specific next step rather than asking if they got it
Day 3EmailAnswer the objection you hear most, then a clear way to book
Day 7SMSThe close-the-loop message. Say it is the last one, and mean it

Out of hours, change the wording rather than the timing. Send immediately, be openly automatic about it, and set the expectation for when a person will follow up. An acknowledgement at 2am is welcome; a 2am message written as though a human typed it, followed by silence until nine, reads as being ignored twice.

First message - example copy, not a template to send unedited

Hi {first_name}, it's Dan at {business}. Thanks for
your enquiry about {offer} on Facebook. Quickest
question first: what's the address of the property?
I'll come back with a price today.
Reply STOP to unsubscribe.

# Why it is shaped this way:
# - names the business (Twilio: identify the sender)
# - names the ad, so they remember tapping it
# - asks ONE question - two questions get one answer
# - carries the required opt-out language

The same cadence logic applies once a price is out the door, which is a separate motion with its own guide: automating quote follow-up picks up where this sequence ends.

The build, step by step

1

Consent line on the form

Add the disclaimer text to the instant form before anything else, and confirm it is visible in the form preview rather than only in the editor. Record the form ID and submission timestamp with every lead. This is the cheapest step and the one that makes the rest defensible.

2

Endpoint, verification and Page subscription

Create the webhook endpoint in your automation platform, complete Meta's verification handshake, subscribe the Page object to the leadgen field, then install the app on the Page with the POST to /subscribed_apps. Verify the signature on inbound deliveries - an unauthenticated public endpoint that triggers outbound SMS is a bill waiting to happen. The webhook entry covers the general shape.

3

Retrieve, map, normalise

Call the Graph API on the leadgen_id, map field_data by name, normalise the phone to E.164, and drop anything that is obviously junk - a phone field with four digits in it should route to a review queue, not to Twilio. Token handling is standard OAuth: store it encrypted, refresh it on a schedule, and alert on failure rather than discovering expiry through a quiet week.

4

Write it down before you act on it

Create the record in your CRM or sheet first, with the ad and form names attached so the sales conversation starts with context. Deduplicate on phone number against existing customers here - texting a current client a new-enquiry greeting is the sort of small error that costs more goodwill than the lead was worth.

5

Send, then get out of the way

Fire the SMS, then notify the team on whatever channel they actually watch. The automation's job is the first sixty seconds. A human closes. Anyone selling you a bot that runs the whole conversation for a high-value service job is selling you a slower way to lose leads - the human-in-the-loop boundary is the design decision that matters most here.

6

Reconcile daily

A scheduled bulk read on the form's /leads edge, compared against what your CRM holds, catches every lead lost to a deploy, an expired token or a platform outage. It takes an hour to build and it is the difference between believing the system works and knowing it does.

How this breaks in production

None of these are hypothetical. Each one is a way a working build stops working without announcing it.

  • The token expires. Page tokens and app installs do not last forever, and the failure is silent: webhooks arrive, retrieval 400s, nobody gets a text. Alert on retrieval failure specifically, not just on workflow errors in aggregate.
  • Somebody edits the form. A new question, a renamed field, a reordered array. Map by name and log any unrecognised field name so the change surfaces the same day.
  • The A2P campaign gets rejected or suspended. Messages stop delivering while your workflow reports success. Monitor delivery status, not send status - these are different things.
  • Nobody answers the replies. The most common failure and the least technical. An instant text that generates a reply nobody reads is worse than no text, because it manufactures an expectation and then breaks it.
  • Retries produce duplicates. Handled by keying on leadgen_id, and only by that. Retry and backoff is worth reading alongside it.

If you run field service work, this build slots into a broader order of operations - the HVAC and plumbing automation page sets out what to build first and what can wait, and missed call text-back is its close relative: same urgency, same compliance surface, different trigger. On budget, what an automation build costs covers the one-off, and AI automation cost covers the running side. Worth tracking the outcome as cost per booked job rather than cost per lead, since cheap leads that nobody answers are the thing this page is trying to fix.

FAQ

Does the Facebook leadgen webhook include the lead's phone number?
No, and this is the single fact that breaks most first attempts. Meta's lead ads webhook documentation shows the notification value containing leadgen_id, page_id, form_id, adgroup_id, ad_id and created_time, and states explicitly that the notifications do not include lead field data - you use the leadgen_id from the notification to retrieve the data associated with the lead. So the webhook is a doorbell, not a delivery. The phone number arrives only after a second call to the Graph API on the lead ID, made with a token carrying the leads_retrieval permission. Verified against Meta's Lead Ads webhooks and retrieval documentation, August 2026.
Which permissions do I need to retrieve lead data?
Meta's retrieval guide lists leads_retrieval, pages_show_list, pages_manage_ads and pages_read_engagement for retrieving all lead data, and its webhooks quickstart lists leads_retrieval, pages_manage_metadata, pages_show_list, pages_read_engagement and ads_management for the webhook integration. The two lists differ slightly, which is normal for Meta docs and worth noting rather than smoothing over - build against the union of the two and drop what you find you do not need. Meta also documents that the app must be installed on the Page via a POST to /subscribed_apps using a Page access token from a person with ADVERTISE permissions. As of August 2026.
How long does Meta keep lead data?
Meta's Business Help Center describes lead information as available for 90 days, after which older leads cannot be downloaded, and its developer documentation calculates the retrieval rate limit as 200 multiplied by 24 multiplied by the number of leads created in the past 90 days for a Page. We could not render the Business Help Center article itself for a verbatim quote - those pages load client-side and returned only a title to our fetch - so we are reporting the 90-day figure as Meta-sourced but not independently re-read on the page. The practical consequence is not in dispute: Ads Manager is not your lead database. Get every lead into a system you own on the day it arrives.
Can I text a Facebook lead straight away?
Only if they consented to being texted. Twilio's messaging policy requires consent that is freely given by each recipient to each sender for each message subject, and informed and unambiguous, meaning the person was told who you are and how their number would be used. It also states that consent cannot be bought, sold, rented or transferred, and that any consent obtained is strictly for the subject matter it was given for. Submitting a form asking for a quote is a strong signal, but the safe build puts an explicit line in the instant form saying the business may text them about their enquiry. That line costs nothing and settles the question.
What has to be in the first message?
Twilio's messaging policy requires that, except for follow-up messages in an ongoing conversation, every message clearly identifies the sender - the party that obtained consent - and that the initial message includes Reply STOP to unsubscribe or an equivalent standard opt-out keyword such as STOPALL, UNSUBSCRIBE, OPTOUT, CANCEL, END, REVOKE or QUIT. It also requires the opt-out process to be a single step. Beyond compliance, the message should name what they enquired about and ask exactly one question, because a message with two questions gets one answer or none.
Do I need A2P 10DLC registration for this?
For US traffic from a standard local number, yes. Brand registration comes first, then campaign registration, and an unregistered or rejected campaign is the reason a great many working builds silently deliver nothing. We wrote the whole process up separately rather than compress it here: see the A2P 10DLC guide for the registration order, the sole proprietor route and its caps, the published fees and the real rejection reasons. Do it before you spend a day on the workflow, because the lead time is the part you cannot compress.
Should I use an off-the-shelf connector instead of building this?
Often, yes, and it would be dishonest to pretend otherwise. If a connector already moves Facebook leads into the CRM you use and that CRM can send the text, take it. Building your own is worth it when you need something the connector will not do: branching on a form answer, checking business hours before texting versus emailing, deduplicating against existing customers, or handling the reply with something smarter than a canned auto-response. The build below is the same either way in its important parts - what changes is who maintains it.
What happens to leads that arrive at 2am?
You still answer, but not with a message that pretends a human is awake. Send the acknowledgement immediately - people expect an instant automated reply and are not offended by one - and set the expectation explicitly: someone will call in the morning, and here is a booking link if they would rather choose a time themselves. The failure mode to avoid is an out-of-hours message written in the voice of a person, which produces a reply that then sits unanswered for six hours and reads as being ignored twice.

Done for you

Want your Facebook leads texted back before they close the app?

We build the whole path: instant form consent wording, the leadgen webhook and Graph API retrieval, deduplication, the first-minute SMS, and the handoff into whatever your team already watches. You get the workflow, the documentation and a plain-language report of what ran. The audit that scopes it is free.

The consult is free, and you keep whatever we build.

Keep building

The rest of the cluster