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 user with the ADMIN role in your organization. Only admins 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 — 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 five 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 five permissions: pages_show_list, pages_manage_metadata, pages_read_engagement, leads_retrieval, and ads_management.

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 five permissions, type its name and select it from the autocomplete:

   • pages_show_list
   • pages_manage_metadata
   • pages_read_engagement
   • leads_retrieval
   • ads_management
   

   Note: if any of the five is missing from the autocomplete, your use case has not enabled it yet. pages_manage_metadata and ads_management are the two that commonly require this; both are opt-in under the use case's Customize view rather than granted by default. 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 five 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.

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 five required permissions; recheck pages_show_list, pages_manage_metadata, pages_read_engagement, leads_retrieval, and ads_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 canonical 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 five required permissions, most commonly ads_management or pages_manage_metadata. Those two 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.

Fix: open your Meta app and go to Use Cases → Capture and manage ad leads with marketing API → Customize → Permissions. Toggle on all five: pages_show_list, pages_manage_metadata, pages_read_engagement, leads_retrieval, ads_management. Then redo Step 5 to regenerate the user access token with the full scope set, and redo Step 6 in Whispyr to reconnect the page with the new token. Whispyr rejects a token that's missing any of the five 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 five required scopes. 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.

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 five 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.