---
url: >-
  https://docs.corbitaltech.dev/products/fblead-addon-for-whatsmarks-saas/facebook-integration.md
description: >-
  Complete guide to integrating Facebook Lead Ads with the Facebook Leads
  Integration & Sync Addon
---

# Facebook Integration

Learn how to connect your Facebook Lead Ads with the Facebook Leads Integration & Sync Addon for seamless lead capture and processing.

## 🏢 Facebook Business Setup

### Prerequisites

Before setting up Facebook integration, ensure you have:

* Facebook Business Account with admin access
* Facebook Page with admin permissions
* Facebook Ad Account with Lead Ads capability
* Active Lead Ad campaigns (or plans to create them)

### Facebook Developer Account

1. **Create Developer Account**: Visit [developers.facebook.com](https://developers.facebook.com)
2. **Verify Account**: Complete phone and email verification
3. **Accept Terms**: Agree to Facebook Developer Terms

## 📱 Facebook App Configuration

### Step 1: Create Facebook App

Follow these visual steps to create your Facebook app for lead integration:

#### Step 1: Access App Creation

Navigate to the Facebook Developers portal and start the app creation process.

![Facebook App Creation - Step 1](./images/meta-app-1.png)

1. **Navigate to Apps**: Go to "My Apps" in Facebook Developers console
2. **Create New App**: Click the "Create App" button
3. **Begin Setup**: Start the app creation wizard

#### Step 2: Choose Use Case

Select the appropriate use case for your Facebook app integration.

![Facebook App Creation - Step 2](./images/meta-app-2.png)

1. **Filter Options**: You can filter by use case categories if needed
2. **Select Use Case**: Choose "Other" from the available options (as shown highlighted)
3. **App Configuration**: This will configure your app for custom business integration needs
4. **Continue Process**: Click "Next" to proceed to app type selection

#### Step 3: Select App Type

Choose the correct app type for your business integration needs.

![Facebook App Creation - Step 3](./images/meta-app-3.png)

1. **App Type Selection**: Choose "Business" as your app type
2. **Business Integration**: This type allows you to create or manage business assets
3. **Permissions Access**: Business apps get access to Pages, Events, Groups, Ads, Messenger, WhatsApp and Instagram
4. **Proceed**: Click "Next" to continue with app details

#### Step 4: Configure App Details

Enter your app information and complete the creation process.

![Facebook App Creation - Step 4](./images/meta-app-4.png)

1. **App Name**: Enter a descriptive name like "Lead Demo" or your business name
2. **Contact Email**: Provide a valid business email address (this will be used for app-related communications)
3. **Business Portfolio**: Select your business portfolio from the dropdown or select without business portfolio
4. **Terms Agreement**: Review and agree to Meta Platform Terms and Developer Policies
5. **Create App**: Click "Create app" to finalize the process

#### Step 5: App Creation Success

Once created successfully, you'll be redirected to your app dashboard where you can begin the configuration process.

## 🔧 Post-Creation App Configuration

### Step 1: Complete Basic App Information

After creating your app, you must complete additional required information before making it live:

#### Required App Details

1. **App Icon**: Upload a professional 1024x1024 pixel app icon representing your business
2. **App Description**: Provide a clear description of your app's purpose (lead collection and integration)
3. **Category**: Select appropriate business category for your app
4. **Contact Person**: Add contact person details (name, email, phone) for Meta communications

#### Privacy & Legal Requirements

**⚠️ Critical Requirements**: These are mandatory for app approval and going live:

1. **Privacy Policy URL**:

   * Must be a publicly accessible web page
   * Should detail how you collect, use, and protect Facebook user data
   * Must comply with applicable privacy laws (GDPR, CCPA, etc.)
   * Example: `https://yourdomain.com/privacy-policy`

2. **Terms of Service URL**:

   * Must outline terms for using your lead capture service
   * Should include user rights and responsibilities
   * Example: `https://yourdomain.com/terms-of-service`

3. **Data Deletion Instructions**:
   * Provide clear instructions for users to request data deletion
   * Can be a URL or contact email
   * Example: `mailto:privacy@yourdomain.com` or `https://yourdomain.com/data-deletion`

#### Business Verification (If Required)

Some regions may require additional business verification:

* **Business Documents**: Upload official business registration documents
* **Address Verification**: Provide verified business address
* **Identity Verification**: Upload government-issued ID for business owner
* **Phone Verification**: Verify business phone number

### Step 2: Configure App Domains and URLs

Set up your app's allowed domains and URLs:

1. **App Domains**: Add your website domain (e.g., `yourdomain.com`)
2. **Authorized Redirect URIs**: Add authorized callback URLs
3. **Webhook URLs**: Add your webhook endpoint URLs (configured later)

### Step 3: Country-Specific Considerations

**⚠️ Important Note**: Meta app creation and approval processes may vary by country and region:

#### Common Regional Variations:

* **United States**: Standard process with business verification options
* **European Union**: Enhanced GDPR compliance requirements and documentation
* **India**: Additional local compliance and business verification requirements
* **Brazil**: Specific business registration and tax ID requirements
* **Other Regions**: May have unique local regulatory requirements

#### General Recommendations:

1. **Check Local Requirements**: Research Meta's specific requirements for your country
2. **Compliance Documentation**: Prepare all required business and legal documentation
3. **Local Legal Review**: Consider legal review of privacy policy and terms for local compliance
4. **Meta Support**: Contact Meta Developer Support for country-specific guidance if needed

### Step 4: Copy Essential App Credentials

Once your app is configured, you'll need to copy these essential credentials for WhatsMarkSaaS integration:

#### Accessing App ID and App Secret

![Facebook App id and App Secret](./images/fb-app-id-secret.png)

1. **Navigate to Basic Settings**:

   * In your app dashboard, go to **Settings > Basic**
   * This page contains your essential app credentials

2. **Copy App ID**:

   * **Location**: Displayed at the top of Basic Settings page
   * **Format**: Numeric string (e.g., `123456789012345`)
   * **Usage**: Required for WhatsMarkSaaS Facebook integration setup
   * **Security**: This can be public-facing in your code

3. **Copy App Secret**:
   * **Location**: In Basic Settings, click "Show" next to App Secret
   * **Format**: Alphanumeric string (e.g., `abc123def456ghi789`)
   * **Usage**: Required for WhatsMarkSaaS authentication
   * **⚠️ Security**: Keep this SECRET - never expose in client-side code or public repositories

### Step 5: Make Your App Live

#### Development vs Live Mode

* **Development Mode**: Limited to app developers and testers only
* **Live Mode**: Available to all Facebook users (required for production)

## 🔑 Permissions Setup

### Step 1: Required Permissions Management

**Critical Permissions Setup**: Request and obtain approval for required permissions:

**⚠️ Critical**: The Facebook Leads Integration & Sync Addon requires these specific Meta app permissions:

* `ads_management` - For managing ads and campaigns
* `pages_manage_ads` - For managing page advertisements
* `pages_manage_metadata` - For managing page metadata
* `pages_read_engagement` - For reading page engagement data
* `leads_retrieval` - For retrieving lead generation data (most important)

**Permission Approval Process**:

1. **Submit App Review**: Submit app for Meta review process
2. **Provide Documentation**: Include detailed use case documentation
3. **Wait for Approval**: Meta review can take several days to weeks
4. **Verify Permissions**: Confirm all permissions are approved and active

**Important Notes**:

* All permissions must be approved by Meta through their App Review process
* We do not provide support for Meta permission approval
* Tenants must handle permission requests and approval directly with Meta
* Without proper permissions, the addon will not function correctly

## 🔗 Webhook Configuration

### Step 1: Add Webhook Product

![Webhook Product](./images/webhook-product.png)

**Add Webhook Support**: Configure webhooks for real-time lead processing:

1. **Add Webhooks Product**: In Meta app dashboard, add "Webhooks" product
2. **Create Page Subscription**: Click on "Page" to create page subscription

### Step 2: Configure Webhook Endpoint

1. **Configure Webhook Endpoint**:
   * **Callback URL**: Enter webhook URL from WhatsMarkSaaS settings
   * **Verify Token**: Enter verify token from WhatsMarkSaaS settings
   * Click "Verify and Save" to establish connection

### Step 3: Subscribe to Events

1. **Subscribe to Lead Events**:
   * After webhook verification, select subscription events
   * Check "leadgen" event subscription (essential)
   * Click "Subscribe" to activate lead event listening
   * Verify "Successfully subscribed to leadgen" confirmation

### Step 4: Verify Webhook

Facebook will send a verification request to your webhook URL with:

* `hub.mode`: "subscribe"
* `hub.challenge`: Random string to echo back
* `hub.verify_token`: Your verify token

## ⚙️ WhatsMarkSaaS Integration Setup

### Step 1: Configure App Credentials in WhatsMarkSaaS

**Enter Meta App Details**: Connect your Meta app with WhatsMarkSaaS:

1. **Access Integration Settings**: Go to **Application Settings > Facebook Lead Integration**
2. **Enable Feature**: Toggle "Enable Facebook Lead Integration" to ON
3. **Enter Meta App Credentials**:
   * **Facebook App ID**: Copy from Meta app basic settings
   * **Facebook App Secret**: Copy from Meta app basic settings
   * **Webhook Verify Token**: System will auto-generate (note this value)
4. **Save Configuration**: Click "Save Settings" to establish connection
5. **Copy Webhook Details**: Note the generated:
   * **Webhook URL** (needed for Meta app webhook configuration)
   * **Verify Token** (needed for webhook verification)

### Step 2: Test Facebook Connection

**Verify Integration**: Ensure proper connection between systems:

1. **Connection Test**: Click "Test Connection" button to verify app credentials
2. **Success Confirmation**: Look for "Connection successful" message
3. **Permission Check**: Verify all required permissions are accessible
4. **Error Handling**: Address any connection errors before proceeding

### Step 3: Connect Facebook Pages

**Link Business Pages**: Configure which Facebook pages to capture leads from:

1. **Fetch Pages**: Click "Fetch Facebook Pages" button in integration settings
2. **Review Available Pages**: System displays all pages linked to your Meta app
3. **Subscribe to Pages**: For each page you want to capture leads from:
   * Find the page in the list
   * Click "Subscribe to Leads" button next to page name
   * Verify status changes to "Subscribed"
   * Repeat for all desired pages
4. **Verify Subscriptions**: Ensure all target pages show "Subscribed" status

### Step 4: Lead Campaign Management

**Create Lead Generation Campaigns**: Set up Facebook Lead Ads:

1. **Access Ads Manager**: Go to [business.facebook.com](https://business.facebook.com)
2. **Create Lead Campaign**:
   * Choose "Lead generation" campaign objective
   * Select subscribed Facebook page from WhatsMarkSaaS
   * Configure target audience and budget settings
3. **Design Lead Form**:
   * Create lead capture form with essential fields (name, email, phone)
   * Add custom qualifying questions based on business needs
   * Include privacy policy link (optional)
   * Set up thank you message for form completion
4. **Launch Campaign**: Publish campaign and monitor lead generation performance

## 📋 Lead Form Setup

### Creating Effective Lead Forms

#### Form Structure

1. **Form Name**: Use clear, descriptive names
2. **Welcome Screen**: Create engaging welcome message
3. **Questions**: Add relevant qualification questions
4. **Privacy Policy**: Include privacy policy link
5. **Thank You Screen**: Add confirmation message

#### Question Types

* **Contact Info**: Name, email, phone (required)
* **Multiple Choice**: Predefined options
* **Short Answer**: Free text responses
* **Conditional Logic**: Dynamic question flow

#### Best Practices

* Keep forms short (3-5 questions max)
* Use clear, simple language
* Avoid asking for sensitive information
* Include privacy reassurance
* Test forms before publishing

## 🔄 Real-time Sync Setup

### Webhook Processing

The FBLead Addon automatically processes Facebook webhooks:

1. **Receives Webhook**: Facebook sends lead data
2. **Validates Request**: Verifies Facebook signature
3. **Processes Lead**: Extracts and stores lead information
4. **Triggers Actions**: Executes configured automation

## 🛡️ Security Configuration

### API Security

* **HTTPS Required**: All API calls must use HTTPS
* **Token Security**: Store tokens securely
* **Request Validation**: Validate all Facebook requests

### Webhook Security

* **Signature Verification**: Verify Facebook webhook signatures
* **Token Validation**: Validate verify tokens
* **IP Whitelisting**: Restrict webhook access to Facebook IPs
* **Request Logging**: Log all webhook requests for audit

## 📊 Testing & Validation

### Test Scenarios

1. **Create Test Lead**: Submit test lead through Facebook form
2. **Verify Webhook**: Confirm webhook receives data
3. **Check Processing**: Ensure lead appears in system
4. **Test Automation**: Verify triggered actions execute

### Common Issues

#### Connection Problems

* **Invalid Credentials**: Check App ID and Secret
* **Permission Issues**: Verify required permissions
* **Network Problems**: Check server connectivity

#### Sync Issues

* **Missing Webhooks**: Verify webhook configuration
* **Processing Errors**: Check error logs
* **Duplicate Leads**: Configure deduplication

## 🔧 Advanced Configuration

### Multiple Ad Accounts

1. **Business Manager**: Use Facebook Business Manager
2. **Account Access**: Grant app access to multiple ad accounts
3. **Account Selection**: Configure which accounts to sync
4. **Permission Management**: Manage account-level permissions

***

*With proper Facebook integration, you'll have a seamless flow of leads from Facebook directly into your WhatsApp engagement system.*