Meta Ads

Every new lead from your Facebook or Instagram lead ads can land in Whispyr within seconds, with full attribution: which page, which form, which campaign, which ad. This guide walks you through the one-time setup, end to end.

Before you start

Check that you have each of these ready. If you miss one, Meta will stop you later in the flow.

• A Facebook Business Manager account with the Facebook Page you plan to run ads on already claimed inside it.
• If you run Instagram Lead Ads: the Instagram Business Account must be linked to the Facebook Page you will connect to Whispyr. Meta requires this at the platform level. Instagram lead events are delivered through the linked Facebook Page, not through a separate Instagram connection.
• A Whispyr account with an admin role: Admin, Umbrella Admin, or Franchise Admin. Only those roles can see Settings → Integrations → Meta.
• 20 to 30 minutes for a first-time setup. You will switch between two browser tabs, one on Meta and one on Whispyr. Keep both open the whole way through.

What you will do

You will create a small Meta Developer App for your company inside Meta's Developer dashboard, then tell that app about Whispyr by pasting a webhook URL and a verify token. Next you will generate a user access token and pick which Facebook Pages to connect inside Whispyr. In the final step, you will publish the app so Meta starts sending real customer leads to it. From that point on, any new lead submitted on a connected page, or on an Instagram Business Account linked to a connected page, will appear in Whispyr with full attribution.

Step 1. Create a Meta Developer App

A Meta Developer App is the object inside Meta's system that receives lead webhooks and holds the permissions Whispyr needs. Each Whispyr customer creates their own app. That model keeps you on Meta's Standard Access level and is the reason Business Verification and App Review are not required (see the FAQ at the bottom).

1. Open https://developers.facebook.com/apps. Log in with the Facebook account that administers your Business Manager.

   

2. Click Create app in the top right.

3. Meta opens a five-panel wizard. Work through each panel in order:

   1. App details. Enter your app name (for example, <Company> CRM) and an app contact email. Click Next.

      

   2. Use cases. Meta lands on the Featured tab by default, which highlights six common use cases. None of those are the correct one for this integration. Click the All tab, then select Capture and manage ad leads with marketing API. Click Next.

      

   3. Business. Pick the Business Manager portfolio this app belongs to and click Next.

      

   4. Requirements. No requirements are needed. Click Next.

      

   5. Overview. The panel summarizes your app and shows an informational "By proceeding, you agree to..." line, with no checkbox to tick. Click Create app to confirm.

      

4. Meta may prompt you to re-enter your Facebook password to confirm the action. If so, enter it and click Submit.

   

Note: Meta renamed and reshuffled app creation recently. There is no longer a standalone Business app type to pick. The use case you pick in panel 2 determines what products and permissions your app gets, and Capture and manage ad leads with marketing API is the one that exposes Webhooks and the leads_retrieval permission under Standard Access.

You now have an empty Meta Developer App. Keep this tab open. You will come back to it several times.

Step 2. Enter your app credentials in Whispyr

In your Whispyr tab, go to Settings → Integrations → Meta. The Enter your Meta app credentials card asks for two values from Meta:

• App ID: copy from Meta's Settings → Basic → App ID.

• App Secret: copy from Meta's Settings → Basic → App Secret. You will see a Show button next to the masked value. Click it. Meta may prompt you to re-enter your Facebook password to reveal the secret.

  

Paste both into the Whispyr form and click Save.

Note: Whispyr encrypts the App Secret the moment you save. It is never stored in plain text and never appears in logs or exports. See the FAQ for the encryption details.

Step 3. Copy your Callback URL and Verify Token

Whispyr generated a Verify Token for your organization the first time an admin opened this page. You never type or choose one yourself. Meta will ask for it in the next step, as a shared secret that proves the webhook request came from the app you just created.

1. In the Configure the Meta Webhooks product card, find the Callback URL value at the top and click Copy. The URL has the shape:

   https://api.whispyrai.com/api/webhook/meta/<your-org-slug>

   

2. Below the Callback URL, find the Verify Token value. The token is masked behind a Reveal button. Click Reveal: a confirmation dialog opens noting that the action writes a row to the audit log. Click Reveal now in the dialog and the token appears, then click Copy.

   

The <your-org-slug> portion is your organization's stable identifier inside Whispyr. It is frozen, meaning it does not change even if you rename your organization, so you can paste this URL once and leave it.

Note: keep both values on your clipboard or in a scratch note. You will paste each one exactly once into Meta in Step 4. Any extra whitespace at the start or end will cause Meta's verification to fail, so prefer the Copy buttons over hand-typing.

Step 4. Configure Meta's Webhooks product

Switch back to your Meta app tab. This step wires Meta's Webhooks product to Whispyr and subscribes the right event field. The moment the handshake succeeds, the Connect your Facebook pages step in Whispyr unlocks.

1. In the left sidebar, click Use cases. On the Use cases page that opens, find Capture and manage ad leads with marketing API and click Customize on its card.

   

2. In the list of items you can customize, find and click Webhooks.

   

3. At the top of the Webhooks page there is a dropdown that defaults to User. Switch it to Page. Lead ads live on Facebook Pages, so Page is the correct object type.

   

4. Two fields appear:

   • Callback URL: paste the Webhook URL you copied from Whispyr in Step 3.
   • Verify Token: paste the Verify Token you copied from Whispyr in Step 3.
   

5. Click Verify and Save.

   

Meta now calls your Whispyr webhook URL with a challenge string. Whispyr compares the verify token, confirms it matches, and returns the challenge. If the handshake succeeds, Meta marks the callback as verified and reloads the page with a subscription panel below the form.

6. Scroll to the list of fields this Page object can emit. Find leadgen and toggle it on.

   

Note: you may also see a Test button on the leadgen row. Skip it. Meta's in-panel Test button is unreliable for the leadgen field and will often silently drop the test event. You'll verify the pipeline end to end after Step 7 (Go Live) using either a real lead submission or Meta's Lead Ads Testing Tool. Neither of those is required by Whispyr, they're sanity-check options.

If Verify and Save fails, it is almost always one of three things:

• Extra whitespace on either pasted value. Re-copy from Whispyr without any trailing space or newline.
• The <org-slug> in the callback URL does not match the slug in your Verify Token card. Re-copy the Webhook URL, do not hand-type it.
• Whispyr is unreachable from Meta's servers. This is rare on production. Staging preview URLs behind a cookie wall will fail here; run the setup against your production Whispyr workspace.

Step 5. Generate a user access token

Whispyr needs a short-lived user access token from you so it can, in one call, list the Facebook Pages you administer and mint a long-lived Page Access Token for each page you choose to connect.

Before you start, make sure all eight permissions Whispyr needs are enabled on your use case. Open Use Cases → Capture and manage ad leads with marketing API → Customize → Permissions and features. Click + Add next to each of these eight permissions: pages_show_list, pages_manage_metadata, pages_read_engagement, leads_retrieval, ads_management, pages_manage_ads, ads_read, and business_management.

Meta's permission reference lists the last two, ads_read and business_management, as requirements for leads_retrieval. Add them even though the rest of this guide never asks you to use them directly.

1. Go to https://developers.facebook.com/tools/explorer/.

   

2. In the top right, find the Meta App dropdown. Select the app you created in Step 1. The dropdown should show your app name, not Graph API Explorer.

   

3. In the User or Page dropdown (just below the Access Token field), select User Token.

   

4. Below the User or Page dropdown, an Add a Permission field appears. For each of the eight permissions, type its name and select it from the autocomplete:

   • pages_show_list
   • pages_manage_metadata
   • pages_read_engagement
   • leads_retrieval
   • ads_management
   • pages_manage_ads
   • ads_read
   • business_management
   

   Note: if any of the eight is missing from the autocomplete, your use case has not enabled it yet. pages_manage_metadata, ads_management, pages_manage_ads, ads_read, and business_management are the ones that commonly require this; they are opt-in under the use case's Customize view rather than granted by default, and Meta will not enable leads_retrieval until ads_read and business_management are on. Switch to your Meta app tab, open Use Cases → Capture and manage ad leads with marketing API → Customize → Permissions, click + Add on the missing ones, then refresh the Graph API Explorer tab and repeat step 3. All eight should now appear.

5. Click Generate Access Token at the bottom of the panel. Meta opens the Facebook OAuth dialog, which walks you through four screens in order.

   

   1. Continue as. Confirm the Facebook account you want to authorize, then click Continue as [name].

      

   2. Page picker. Facebook lists every Page you administer. Tick every Page you want Whispyr to receive leads from. This is where access is actually granted. Pages you don't tick here won't appear in Whispyr later, even if you administer them on Facebook. Click Next.

      

   3. Access review. Facebook lists the permissions your app is requesting against the pages you ticked. Leave each switch enabled and click Save.

      

   4. Confirmation. Facebook confirms the connection. Click Got it to dismiss.

      

6. The dialog closes and the Access Token field at the top of the Graph Explorer fills with a long string. Click the copy icon on the right of the field.

   

Note: do not close the Graph Explorer tab until you finish Step 6. If the token expires before you paste it, redo this step. A fresh login gives you a token that can be exchanged for a long-lived one. A recycled older token cannot.

Step 6. Connect your Facebook pages in Whispyr

Back in Whispyr, in Settings → Integrations → Meta, scroll to the Connect your Facebook pages card.

1. Paste the user access token you just copied from the Graph Explorer into the input field.

   

2. Click Next. Whispyr calls Meta in the background to exchange your short-lived token for a long-lived one (about 60 days of life) and to fetch every page you administer.

   

3. You see a list of your pages. Tick the ones you want to connect. Pages already connected are greyed out with a Connected label.

   

4. Click Connect N pages (the button label shows the count of selected pages, for example Connect 2 pages). For each ticked page, Whispyr validates the token, encrypts it at rest, and subscribes the page to the leadgen webhook field on your app.

5. Each row shows a status. A green check means the page is live and ready. A red cross means something broke on that specific page. Hover the red cross to see the exact Meta error, then consult Troubleshooting below.

Manage your connected Pages

Once a page is connected, the Meta settings page shows a Manage Pages card listing every Facebook Page Whispyr routes leads from. On a phone the same rows render as cards, carrying the same facts.

Each row shows:

• Page: the page name, its Page ID, and the Facebook category.
• Source: Your app for a page connected through the Meta app you created in Step 1, Whispyr app for one Whispyr connected on your behalf.
• Health: Healthy, Checking, Needs attention, or Disconnected, with the time of the last check under it and, when something is wrong, a short reason such as Token expired or Webhook subscription missing. Open Health details for the seven individual checks behind that badge: Page visibility, Page task or Leads Access, Required user permissions, Page token, Lead-form access, Webhook subscription, and Lead reconciliation. Each one carries its own status and, where Meta returned them, the permissions the check required against the permissions it got.
• Lead forms: All current and future, N selected, or Paused. See "Choose which forms create leads" below.
• Connected by and Connected: who added the page, and how long ago.

The actions on a row are Refresh health, Repair Page, Choose forms, Reveal and Disconnect. Repair Page appears only on a page that needs it.

Refreshing health. Refresh health in the card header rechecks every page; the same action on a row rechecks that one page. Whispyr also rechecks quietly when you open the page and the last check is more than fifteen minutes old.

Adding more pages. Manage Pages in the card header opens Manage Facebook Pages. It asks for a fresh short-lived user access token, generated exactly as in Step 5, and lists the permissions that token needs. Whispyr uses the token for that session only and does not save it. Click Refresh from Meta and the full inventory loads.

Above the list, eight counts describe what came back:

• Meta reported: how many pages Meta says this token can see.
• Loaded by Whispyr: how many pages Whispyr actually read back, with duplicate Page IDs removed.
• Connected, Available, Needs reconnect, Disconnected and Another franchise: how the inventory splits by state. Another franchise means the page is already connected under a different franchise.
• Selected: how many you have ticked so far.

If Meta could not hand back the whole list, Meta returned an incomplete Page list appears above the counts. You can still work with everything shown, and clicking Refresh from Meta again tries for the missing pages.

Searching. Search by Page name or ID filters on either value, so pasting a Page ID jumps straight to it. Select all eligible ticks every page in the current filter that can be connected, and Clear selection empties the whole selection. A page that is already connected and healthy is not tickable and reads Healthy, unchanged; a page held by another franchise reads Connected to that franchise. Click Connect N Pages to finish.

Reconnecting one page. Repair Page on a row opens the same dialog and asks for a token as usual. Once the inventory loads, the dialog is titled Reconnect "your page name" with that page already searched for and ticked, and the button reads Reconnect this Page. If the token cannot see that page, the dialog answers Meta did not return "your page name" and asks you to check the user's page access and Leads Access assignment before refreshing with a token that can see it.

When a connect is partial. If some pages connect and others do not, the dialog stays open with Some Pages did not connect at the top. Everything else connected, and the pages that did not are left exactly as they were. Each one is listed by name with the reason Meta gave, and the list stays on screen until you close the dialog or start another connect, so you can read every reason before you leave.

What "needs to be reconnected" means. A page leaves Healthy when its Meta token expires or Meta withdraws it, which happens when a page admin is removed, a password changes, or someone revokes the app's access. The page then shows Needs attention with the reason, a banner appears above the cards saying the page needs to be reconnected, and new leads on that page stop arriving until it is fixed. Go to Connected Pages in the banner jumps to the table. Fix it with Repair Page on the row and a fresh token.

Disconnecting. Disconnect asks you to confirm by page name. Whispyr marks the page inactive and keeps its lead history, and separately asks Meta to unsubscribe it. The result reports both of those outcomes, so you can see whether Meta accepted the unsubscribe.

Choose which forms create leads

A connected page starts on All current and future forms: every form on the page today, plus any form you add later, creates leads with nothing to maintain. That is the recommended setting.

To change it, click Choose forms on the page's row. Two options are offered:

• All current and future forms, marked Recommended.
• Only selected forms, for a page that carries forms which should not create Whispyr leads.

Pick Only selected forms and the page's forms appear underneath, twenty-five at a time with Showing 1 to 25 of N and arrows to move between pages. Search forms narrows the list, and the count of what you have ticked sits beside the search box. Each form shows its name, or Unnamed form, its form ID, and any badges that apply:

• Selected: this form creates leads.
• Archived: Meta has archived the form.
• Missing from Meta: Meta no longer returns this form.
• New: the form arrived on the most recent refresh.
• Renamed: the form has been renamed since Whispyr first saw it.

Refresh forms, at the bottom left, pulls the current list from Meta. It is unavailable while the page needs reconnecting. If Meta could not return the whole list, The form list is incomplete appears and Only selected forms cannot be chosen until a refresh brings back a complete list.

Switching from all forms to a selection. Saving shows Confirm forms that will stop and names every form that creates leads today and will not after the change, including forms on list pages you never opened. Future leads from those forms are still collected and then set aside; leads already in the CRM and their history are untouched. Keep editing takes you back, Confirm and save applies it.

An empty selection pauses the page. Untick everything and Lead intake is paused appears while you edit. Saving asks Pause all lead intake from this Page? The page stays connected, and every future lead is set aside until you select a form or go back to all forms. The page's Lead forms cell then reads Paused.

A page with more forms than the dialog can list says This Page has too many forms to list. Keep that page on all current and future forms, and contact support if it has to take leads from a selection.

You can also make this choice before a page is connected. In the Connect dialog, a ticked page shows All current and future forms with a Choose forms button beside it. That opens Select forms before connecting, which reads the page's forms straight from Meta. Use all forms instead returns to the default, and Use N selected forms saves the choice for the moment the page connects.

When Meta adds a form later. On a page set to a selection, a form Meta adds afterwards does not create leads until you add it. Whispyr notifies your admins in the app and by email: New form on "your page name", with the line Leads from "the form name" are not coming in yet. Add it in the Page's form settings to start receiving them. The notification links straight to the page. Each admin hears about each new form once.

Bring in older Meta leads

Leads that were submitted before you connected a page, or while a form was not selected, can still be brought into Whispyr. Start from the Historical Meta leads card at the bottom of the Meta settings page and click New import.

Preview historical Meta leads asks for four things:

1. Facebook Page. One page per import. A page that needs reconnecting is still listed, but it cannot be chosen and is marked Reconnect required with a note pointing you at Connected Pages.
2. Date range. It opens on the last 30 days, and you can choose an earlier range.
3. Lead forms. Only the forms the page currently sends leads from can be scanned, so a page on a selection offers that selection.
4. Lead timestamp. Use the original Meta submission time puts the lead and its occurrence on the day the person filled in the Meta form. Use the import time dates them from the import instead. Either way, the original Meta submission time is shown on the review screen.

Click Scan and preview. The scan creates no leads. Whispyr fetches the submissions in range, sets aside every one whose Meta ID is already in the CRM, and opens a record-by-record review.

The review screen. The header carries the page name, the date range, the import's status and four counts: Found on Meta, Already in CRM, New submissions, and Need a decision. If a form could not be read, Some forms could not be scanned names it with the reason.

Every new submission is listed on the left. Search by name, phone, email, campaign or Meta ID, filter by All people, New people or Already a person, and filter by All decisions, Needs decision, Ready or Resolved. Tick rows and the toolbar applies one decision, and one assignment, to all of them at once. Click a submission to see every field Meta sent, the CRM person it matched, and how the match was found.

The decisions. For a submission that matched someone already in the CRM:

• Attach here, on one of that person's lead cards, adds the submission to that existing lead.
• Use current CRM rules places it the way a live lead from that page would be placed today.
• Create a separate lead gives the same person a new lead, kept apart from their existing ones.

For a submission with no match, the choice is Import as a new person. Any submission can be given Skip this submission, which creates nothing.

Assignment. Assignment if this creates a lead sits above the decision buttons: Automatic assignment, Leave unassigned, a team, or one person. It applies only to the two decisions that create a lead, importing as a new person and creating a separate lead.

Running the import. While an existing-person match is undecided, the footer reads Resolve all N existing-person matches to continue and the button stays disabled. Once every new submission has a decision, it reads Every new submission has an import decision and the button becomes Import N reviewed submissions. Confirming opens Confirm historical import: each submission is checked again as it runs, and anything that reached the CRM in the meantime is skipped.

Stopping and resuming. While a scan or an import is running, Stop import is on screen. Confirming it stops the run: submissions already imported stay in the CRM, the rest are left untouched, and you can start a new import later. An import that was stopped, failed, or could not read one of its forms shows Resume beside its status in the header.

When the run ends you see Import complete, Import stopped or Import needs attention, with the tally: how many were imported, attached, created as separate leads, skipped by choice, skipped because they were already in the CRM, and failed. The Historical Meta leads card keeps every past import with its status, from Scanning and Ready for review through Completed, Completed with issues, Stopped and Failed. Click one to reopen its review.

Telling imported leads apart. A lead that arrived through a historical import carries an Imported badge in Settings → Integrations → Webhook Logs, so a backfilled lead is never confused with one that arrived live.

The limits. One import scans up to 500 forms. Above that, the dialog names the count you selected and asks you to untick the rest, and a page carrying more forms than one import can read says This Page has too many forms to scan at once. Meta also returns only the submissions it still holds for a form, so an import brings back what Meta has kept, and Whispyr makes no promise about how far back that reaches.

Step 7. Publish your Meta app (switch to Live Mode)

A freshly-created Meta Developer App starts in Development Mode. In Development Mode, webhooks only fire for users who have a role on the app, which means real customer leads are dropped on the floor. To receive them, switch the app to Live Mode. This is the terminal setup step. Once Live, the integration is active and real leads flow to Whispyr immediately. Whispyr does not gate production leads on a test, the act of going Live is itself the go-ahead.

Before Meta flips the toggle, it checks four things on your app. All four are covered by Whispyr; you copy a few values across.

• App Icon, 1024 by 1024 pixels. Any branded image works. A cropped logo is fine. PNG or JPG.
• Category. Pick Business and Pages.
• Privacy Policy URL. Hosted by Whispyr.
• Terms of Service URL. Hosted by Whispyr.

In Whispyr, on the Meta setup page, scroll to the Publish your Meta app card. The first time you open this card, it asks how you want to handle Meta's Privacy Policy and Terms of Service requirements. Two paths are offered.

Use Whispyr's hosted documents (recommended)

Click Use Whispyr's hosted docs. A dialog titled Before you connect Meta opens with two pre-filled fields:

• Legal entity name. Defaults to your organization's name. Edit it if your registered legal name differs from your display name. This is the entity that appears as the data controller on the hosted Privacy Policy, Terms of Service, and Data Deletion Instructions pages.
• Data-deletion contact email. Defaults to your account email. Edit it if you want a different mailbox to receive end-user data-deletion requests.

Use Review privacy policy and Review terms of service to preview the rendered documents inline (they open in an in-app preview, not a new tab). Skim each one and confirm it describes your business correctly.

Tick I agree to these documents on behalf of [legal name], then click Agree and continue.

Or use your own privacy and terms

If you already have a compliant Privacy Policy and Terms of Service hosted on your own domain and configured on your Meta app, click I'm already live instead. Whispyr records your acceptance without surfacing hosted URLs, and you can skip directly to flipping the Meta toggle below.

Once you've agreed to the hosted documents, the Publish your Meta app card lists the three URLs you need. Copy each one:

• Privacy Policy URL
• Terms of Service URL
• Data Deletion Instructions URL

The third URL is the page Whispyr hosts on your behalf that explains, in plain language, how your end users request their data be deleted. You do not paste it into any Meta field. You share it with any customer who asks (see the FAQ).

Switch to your Meta app tab.

1. Open Settings → Basic in the left navigation.

2. Paste the Privacy Policy URL into the Privacy Policy URL field.

   

3. Paste the Terms of Service URL into the Terms of Service URL field.

   

4. Upload your App Icon in the App Icon field.

   

5. Choose Business and Pages in the Category dropdown.

   

6. Click Save Changes at the bottom of the page.

   

Now flip the mode.

1. Go to App Dashboard → App Mode, or the Development / Live toggle at the top of the dashboard.
2. Click the toggle to switch from Development to Live. Confirm the switch in the dialog Meta opens.

Your app is now in Live Mode. Every new lead submitted on a connected page, or on an Instagram Business Account linked to a connected page, arrives in Whispyr within seconds, lands in the right lead list, routes through your automation rules, and carries full attribution: page name, form name, campaign, ad set, and ad.

Note: Meta does NOT require Business Verification or App Review for this integration. Those reviews are only triggered for apps that need to read data from other businesses' pages, what Meta calls Advanced Access. Your app reads data only from your own pages. That falls under Standard Access, which is granted automatically to Business-type apps. If a Meta dialog ever suggests App Review is required to go Live, it is describing a different flow. You can ignore it and continue with the steps above.

Optional: verify the integration end to end

The integration is already active as of Step 7. The Integration health card on the Meta settings page doubles as a liveness indicator: it shows the time of the last webhook Whispyr received and the time of the last lead it successfully fetched via the Graph API. If leads are flowing, those timestamps update automatically on every ingest.

If you want to deliberately fire a test lead without waiting for a real one, you have two options:

• Lead Ads Testing Tool. Open the Lead Ads Testing Tool and dispatch a sample submission against one of your real ad forms. The Testing Tool only dispatches when your Meta app is in Live Mode, in Dev Mode it leaves test leads stuck on Pending forever with no error. This is the most common pitfall and the reason Whispyr does not gate setup on a test lead.

  

• Real admin submission. Open any of your Meta lead ads in Ads Manager, click Preview, and fill out the form using a Facebook account that has a role on your app. This path works in Dev Mode too, since Dev-Mode webhooks fire for app-role users.

Either path updates the Integration health card timestamps within a few seconds of the lead landing.

Screenshots verified against Meta's UI as of 2026-04-26. If a screen looks noticeably different from yours, the underlying step is the same. Meta moves buttons more often than they remove them.

Troubleshooting

"Verify and Save" fails on Meta's side

The verify token or callback URL does not match what Whispyr expects. In order of likelihood: trailing whitespace on either value, a hand-edited org slug in the callback URL, or Whispyr being unreachable from Meta's servers. Re-copy both values from Whispyr using the Copy buttons, do not hand-type either one. Staging preview URLs that require a cookie to access will always fail this step. Run the full setup against your production Whispyr workspace.

Pages don't appear in the Connect dialog

Three possible causes. First, the access token was generated without all eight required permissions; recheck pages_show_list, pages_manage_metadata, pages_read_engagement, leads_retrieval, ads_management, pages_manage_ads, ads_read, and business_management in Step 5. If any of them wasn't available in the permissions dropdown, follow the note in Step 5 to enable it under the use case's Customize → Permissions tab. Second, the token expired before Whispyr could exchange it; generate a fresh one and try again. Third, the Facebook user whose token you pasted is not an Admin on the missing pages. Meta only returns pages where that user has the Admin role, not Editor, Moderator, or Analyst.

The Lead Ads Testing Tool returns "Required permissions are missing for the app"

The Lead Ads Testing Tool is the standard way to fire a test lead against your webhook end to end. If it refuses to send with this error, your user access token is missing one or more of the eight required permissions, most commonly ads_management, pages_manage_metadata, or pages_manage_ads. Those three are not granted by default when you add the "Capture and manage ad leads with marketing API" use case to your app; they need to be toggled on explicitly. ads_read and business_management sit in the same group, and Meta lists both as requirements for leads_retrieval.

Fix: open your Meta app and go to Use Cases → Capture and manage ad leads with marketing API → Customize → Permissions. Toggle on all eight: pages_show_list, pages_manage_metadata, pages_read_engagement, leads_retrieval, ads_management, pages_manage_ads, ads_read, business_management. Then redo Step 5 to regenerate the user access token with the full set, and redo Step 6 in Whispyr to reconnect the page with the new token. Whispyr checks the token when you paste it in Step 6, and the error message names the exact missing permissions.

Subscribe fails on one page but succeeds on others

The page-level subscribe step has its own failure mode, independent of the app-level webhook setup. Two common causes. First, the page is not claimed inside your Business Manager; you can run ads from it but not subscribe its leadgen events. Second, the page has a compliance lock on it from Meta (for example, pending policy review). Open the page in Business Manager, resolve the lock, then retry the Connect flow in Whispyr.

Instagram leads aren't landing

Instagram Lead Ads do not produce their own webhook events. They produce events on the Facebook Page linked to the Instagram Business Account, and the event arrives with object: "page" and change.field: "leadgen". If Instagram leads are missing, open your Instagram account settings inside Meta Business Suite and confirm the linked Facebook Page is one that Whispyr is subscribed to under Connected Pages. If the linked page is different, either relink Instagram to a subscribed page or subscribe the currently-linked page in Whispyr.

Tokens expired faster than expected

If a page's status flips to Reconnect required after only a few hours or days instead of roughly 60, the token you pasted in Step 5 was still short-lived when Whispyr received it. The long-lived exchange only works when the input token came from a fresh login with all eight required permissions. Redo Step 5 end to end, paying attention to the Add a Permission field. Do not reuse a token from an earlier Graph Explorer session.

"Reconnect required" banner in Whispyr

Whispyr runs a background token-health check on every connected page. When it observes expiry, or sees Meta revoke the token because a page admin was removed, a password was changed, or a user revoked app access, it flips the page to Reconnect required and shows the banner. Click Reconnect on the page row, paste a fresh user access token generated the same way as in Step 5, and confirm. The long-lived page token is replaced in place, and no lead history is lost.

A lead was not created because the form is not selected

Open Settings → Integrations → Webhook Logs and find the delivery. If its status reads Not in the selected forms, Meta delivered the lead and Whispyr set it aside on purpose: the page is on Only selected forms and this form is not one of them. The delivery was recorded, and nothing was written to the CRM.

Fix: open the page's Choose forms and tick that form, or move the page back to All current and future forms. From then on, new leads from that form create leads normally. Leads that arrived while the form was unselected are not created retroactively; bring them in with a historical import.

If the form is new, your admins will also have received a New form on "your page name" notification pointing at the same place.

An import stopped or shows Completed with issues

Open the import from the Historical Meta leads card and read the header.

• Stopped means someone confirmed Stop import. Everything imported before that point is in the CRM and the rest was left untouched.
• Completed with issues or Failed means some submissions did not import, and the tally under the status says how many. A reason appears in place of the tally when the whole run failed for one cause, for example Meta refusing to return the submissions.
• Some forms could not be scanned in the header names each form the scan could not read, with its reason.

Click Resume beside the status to continue. It reappears on an import that was stopped, failed, or could not read one of its forms. Submissions already in the CRM are skipped on the way through, so resuming never duplicates anything. If Meta was the cause, wait a few minutes before resuming.

A page needs to be reconnected after a health refresh

Refresh health rechecks each connected page against Meta, so a page that looked fine yesterday can come back as Needs attention. The short line under the badge is the reason: Token expired, Permissions missing, Webhook subscription missing, Lead-form access denied, Facebook session invalidated, and so on.

Open Health details on that row before doing anything else. It breaks the result into seven checks and, for the permission checks, names exactly which permissions Meta granted and which are missing. That tells you whether you need a new token or a change on Meta's side:

• Missing permissions or an expired or rejected token: click Repair Page and paste a fresh user access token, generated as in Step 5 with all eight permissions.
• Webhook subscription missing: reconnecting the page resubscribes it to the leadgen field.
• Page task or Leads Access not healthy: the Facebook user needs Leads Access, or the Create content, Manage, or Moderate task on that page in Business Manager. Grant it there, then refresh health again.

Frequently asked questions

Do I need Meta Business Verification?

No. Business Verification is only required when an app needs to read data from other businesses' pages (what Meta calls Advanced Access). Your app reads only from your own pages, which qualifies for Standard Access. Standard Access is granted automatically to Business-type apps.

Do I need to submit the app for App Review?

No. App Review is Meta's gate for Advanced Access, not Standard Access. The eight permissions this integration uses are covered under Standard Access for a Business-type app, and no submission is required.

Whose privacy policy and terms are these?

Yours. Whispyr hosts the content on a URL we own, but the policy and the terms both identify your company as the data controller, using the legal name and contact email you confirmed on the agreement screen in Step 7. You can open the hosted pages at any time from the Publish your Meta app card and review what a visitor to those URLs would see.

How do customers request their data be deleted?

They email the contact address you provided when you agreed to the hosted documents. The Data Deletion Instructions page explains this to them and tells them exactly what to include. Whispyr does not auto-delete data in response to those emails. The request needs to go through your organization's own process, and your team acts on it inside Whispyr the same way you would for any other customer request.

Can I use my own privacy policy and terms instead?

Yes. If you already have a compliant privacy policy and terms of service on your own domain and you'd prefer those over the Whispyr-hosted versions, contact Whispyr support and we'll switch your organization over.

What happens if I rename my company in Whispyr after setup?

The hosted legal document URLs stay stable. They use a frozen slug captured when you first agreed, so the callbacks and references you gave to Meta never break. The visible content of those pages does update: if you edit the legal company name or the contact email inside Settings → Integrations → Meta, the rendered privacy policy, terms, and data deletion instructions all reflect the new values on the next page load.

Does Whispyr ever see my App Secret in plain text?

No. All three sensitive values on this page, the App Secret, the Verify Token, and each Page Access Token, are encrypted at rest with AES-256-GCM before they are written to the database. Whispyr decrypts them only in memory, and only at the exact moment they are needed: the App Secret for verifying webhook signatures, the Verify Token during the initial handshake, and a Page Access Token when fetching the full lead payload for an incoming event. None of these values ever appear in logs, exports, or the UI after you save them.