Facebook Lead Ads

The API adapter is implemented. Validate your own account and authorized actions before routing production calls.

Before you start

Connect the account belonging to this business and workspace. Vendor subscriptions, API limits and role permissions still apply.

API: Meta Graph API v25.0 / Lead Ads / Page leadgen webhooks

Authentication: Page access token plus appsecret_proof; HMAC-SHA256 signed webhooks

Get access and connect

1. Create a Meta developer business app, connect the Facebook Page and request Lead Ads access.
2. Generate an authorized Page access token with the required permissions and assign the app/user access to leads in Business Settings.
3. Enter the Page ID, Page token and Meta app secret in Verbatik. Choose a new private verification token.
4. Configure the connection's /facebook-leads callback URL and the same verification token in the Meta app's Page webhook settings, subscribing to leadgen.
5. Enable changes and run Subscribe Page to lead notifications. Submit a Meta test lead and confirm it appears as a contact with unknown consent.
6. For other businesses, complete Meta App Review/Advanced Access. Grant calling/texting consent separately before enrolling leads in outbound campaigns.

Account requirements

• A Meta developer app and Facebook Page administrator/lead access.
• Business verification and App Review/Advanced Access may be required for production third-party Pages.
• The integration imports contact data and does not automatically place calls or send SMS.

Permissions

• leads_retrieval
• pages_manage_metadata
• pages_show_list (when selecting Pages)
• pages_read_engagement (when required by the app's permission flow)

Grant the subset needed for the actions you enable. API scopes do not override the connected user’s record permissions or vendor validation rules.

Connection fields

• accessToken — Facebook Page access token (required). Secret fields are saved as workspace credentials.
• appSecret — Meta app secret (required). Secret fields are saved as workspace credentials.
• verifyToken — Webhook verification token (required). Secret fields are saved as workspace credentials.
• pageId — Facebook Page ID (required).
• formId — Only import this form ID (optional) (optional).

Available actions

• test_connection — Read. Read the connected Facebook Page identity without creating or changing leads.
• list_forms — Read. List lead forms owned by the connected Facebook Page. Use the next cursor in a later request for more forms.
• read_lead — Read. Read the fields a person submitted in a Facebook Lead Ad. A form submission does not establish permission to call or text.
• list_form_leads — Read. Read leads from a Facebook Lead Ad form. Preserve any paging cursor; do not infer calling consent.
• subscribe_page — Write. Subscribe the configured Meta app to leadgen webhooks for this Page. First configure this connection's callback URL and verification token in Meta.

Provider-specific behavior

Lead import does not place a call or send SMS. Imported contacts have unknown calling/texting consent until your workspace records the required permission. See Facebook lead webhook.

Verify before going live

Run Test connection and one read action against a known permitted record. Then test each intended write in an authorized sandbox. Check the provider’s own record and the Verbatik receipt. Publish the agent after assigning its tools. If a write has an unknown outcome, reconcile it with the vendor before trying again.

Vendor documentation

• Setup and API documentation
• Additional provider reference