Step 1: Facebook App Configuration

Create Facebook Business App: Go to developers.facebook.com and create a new Business application.

Add Lead Ads Product: In your app dashboard, add the "Lead Ads" product to enable lead form access.

Required Permissions:
• leads_retrieval - Access lead data
• pages_manage_ads - Manage page ads
• pages_read_engagement - Read page engagement
• ads_management - Manage ads

OAuth Redirect URL: Configure https://your-odoo-domain.com/crm_facebook_lead/auth

Step 2: Configure Odoo Module

Install Module: Install "CRM Facebook Lead Ads - LucidBrainz" from Odoo Apps.

Navigate to Settings: Go to CRM → Configuration → Facebook Lead Ads Settings

Enter Credentials:
• App ID: Copy from Facebook App Settings → Basic
• App Secret: Copy from Facebook App Settings → Basic

Authenticate: Click "🔑 Authenticate with Facebook" button
• Redirects to Facebook login
• Grant all required permissions
• Access token auto-saved to Odoo

Step 3: Import Facebook Pages & Forms

Import Pages: Click "📥 Import Facebook Pages" button in settings
• All pages where you have admin access are imported
• Each page gets its own access token
• Company assignment can be configured per page

Fetch Lead Forms: Open any imported page and click "Get Forms"
• All active lead forms are automatically imported
• Form questions become field mapping options
• Status tracking ensures only ACTIVE forms sync

Form Configuration:
• Set destination: CRM Lead or HR Applicant
• Assign Sales Team (CRM) or Job Position (HR)
• Configure UTM tracking (Campaign, Source, Medium)
• Set "Fetch Leads After" date to control sync window

Step 4: Smart Field Mapping

Automatic Field Detection: Click "Get Fields" button to fetch all form questions
• Facebook field keys automatically populated
• Field labels displayed for easy identification

Mapping Options:
1. Manual Mapping: Select Odoo field for each Facebook field
• Supports: char, date, datetime, float, integer, many2one, selection, phone, text
• Search and select from all available fields

2. Auto-Guess Mapping: Click "Guess Mapping" for intelligent auto-mapping
• Uses default mapping templates
• Matches common fields like full_name → Contact Name
• Saves hours of manual configuration

3. Default Mapping Templates: Create reusable templates in CRM → Configuration → Default Field Mappings
• New forms automatically apply these templates
• Standardize mappings across all forms

Step 5: Automatic Lead Synchronization

Scheduled Actions: Two CRON jobs run hourly
• Fetch Facebook Leads (CRM): model.get_facebook_leads()
• Fetch Facebook Recruitment (HR): model.get_facebook_recruitment()

Sync Process:
1. Calls Facebook Graph API v7.0 for each configured form
2. Fetches leads with parameters: created_time, field_data, ad tracking
3. Processes leads with duplicate detection
4. Creates or updates records based on:
• Facebook Lead ID (primary)
• Email address (secondary)
• Phone number (tertiary)
5. Maps fields according to configuration
6. Creates UTM records (Campaign, AdSet, Ad)
7. Commits transaction and processes next page

Error Handling:
• Savepoint for each lead creation
• Continues processing if one lead fails
• Detailed logging for troubleshooting
• Automatic retry on duplicate constraint violations

Step 6: Automated Lead/Applicant Creation

CRM Lead Creation:
• Contact Name: Mapped from full_name or similar field
• Email: Auto-populated from email field
• Phone/Mobile: From phone/mobile fields
• Company: Based on form configuration
• Sales Team: Assigned from form settings
• Campaign/Source/Medium: UTM tracking data
• Facebook Lead ID: Unique identifier
• Facebook Form: Link to source form
• Facebook Page: Source page reference
• Is Organic: Paid vs organic classification
• Created Date: From Facebook timestamp
• Description: Formatted notes with emojis

HR Applicant Creation:
• Applicant Name: From form data
• Job Position: Assigned from form configuration
• Email/Phone: Contact information
• Stage: Initial Qualification stage
• Company: Multi-company support
• Facebook Tracking: Complete ad attribution
• Description: All form responses formatted

Formatted Description: Uses emojis for visual appeal
👤 Contact Name | 📧 Email | 📱 Mobile | 🏙️ City | ✅ Other Fields

Step 7: Intelligent Duplicate Prevention

Three-Level Detection:

Level 1 - Facebook Lead ID (Primary):
• Searches for existing record with same facebook_lead_id
• Most reliable method as Facebook IDs are unique
• Forces database commit to see recent changes

Level 2 - Email Match (Secondary):
• If no Facebook ID match, searches by email_from field
• Updates existing contact with Facebook lead ID
• Prevents duplicate contacts with same email

Level 3 - Phone Match (Tertiary):
• Final check using phone number
• Handles cases where same person uses different email
• Completes the contact deduplication strategy

Update Strategy: When duplicate found:
• Adds missing Facebook Lead ID
• Fills empty email/phone fields
• Assigns company if missing
• Updates UTM tracking data
• Sets facebook_is_organic flag
• Increments existing_lead_count
• Marks as 'Recaptured' lead

Step 8: Complete UTM & Ad Tracking

Automatic UTM Record Creation:

Campaign Tracking:
• utm.campaign - Created from campaign_id and campaign_name
• Reuses existing campaign if facebook_campaign_id matches
• Links to crm.lead for reporting

AdSet Tracking:
• utm.adset - New model for Facebook AdSet hierarchy
• Tracks adset_id and adset_name from Facebook
• Prevents duplicate AdSet records

Medium/Ad Tracking:
• utm.medium - Extended with facebook_ad_id field
• Stores ad_id and ad_name from Facebook
• Links to lead via medium_id field

Complete Attribution Chain:
Campaign → AdSet → Ad → Lead

Enables powerful reporting:
• Which campaigns generate most leads?
• Best performing ad sets?
• Individual ad effectiveness?
• ROI calculation per campaign?

Complete Data Flow Diagram

End-to-End Process:

📱 User Submits Facebook Lead Ad Form ↓ ☁️ Facebook Stores Lead in Cloud ↓ ⏰ Odoo CRON Runs (Every Hour) ↓ 🔍 API Call to Facebook Graph v7.0 GET /form_id/leads?fields=created_time,field_data,ad_tracking ↓ 📥 Lead Data Received {id, created_time, field_data, ad_id, campaign_id, is_organic} ↓ 🔎 Duplicate Check (3 Levels) 1. facebook_lead_id → 2. email → 3. phone ↓ ✅ New Lead → CREATE | 🔄 Existing → UPDATE ↓ 🗺️ Field Mapping Applied Facebook Fields → Odoo Fields (per configuration) ↓ 📊 UTM Records Created/Linked Campaign → AdSet → Ad ↓ 💾 Lead Saved to Database crm.lead or hr.applicant ↓ 📝 Transaction Committed ↓ ✨ Lead Visible in Odoo CRM/HR
Processing Time: Leads appear in Odoo within 1-60 minutes depending on CRON schedule and API response time.

Key Benefits & ROI

✅ Time Savings:
• Eliminates 100% manual data entry
• Saves average 5-10 minutes per lead
• For 100 leads/month = 8-16 hours saved

✅ Data Accuracy:
• Zero transcription errors
• Complete form data captured
• Automatic validation

✅ Marketing ROI Tracking:
• Know exactly which campaigns convert
• Calculate cost per lead by campaign
• Optimize ad spend based on data

✅ Sales Efficiency:
• Leads available in CRM within 1 hour
• Complete contact information ready
• Sales team focuses on calling, not data entry

✅ Multi-Brand Management:
• Perfect for agencies managing multiple clients
• Each brand's leads properly segregated
• No cross-contamination of data

Getting Started

1. Install Module: Go to Apps → Search "Facebook Lead" → Install
2. Configure Settings: Navigate to CRM → Configuration → Facebook Lead Ads Settings
3. Create Facebook App: Visit developers.facebook.com/apps and create Business App
4. Enter Credentials: Input your Facebook App ID and App Secret in Odoo
5. Authenticate: Click "Authenticate with Facebook" button and grant permissions
6. Import Pages: Click "Import Facebook Pages" to sync your pages

Form Configuration

1. Access Pages: CRM → Configuration → Facebook Pages
2. Get Forms: Open any page and click "Get Forms" button
3. Configure Form: Open form and click "Get Fields"
4. Set Destination: Choose CRM Lead or HR Applicant
5. Map Fields: Match Facebook fields to Odoo fields or use "Guess Mapping"
6. Assign Team/Job: Set Sales Team (CRM) or Job Position (HR)
7. Set UTM: Configure Campaign, Source, Medium for tracking
8. Save: Configuration is ready for automatic sync

Managing Leads

• View CRM Leads: CRM → Leads → Filter by Source = Facebook
• View HR Applications: Recruitment → Applications
• Facebook Info Tab: Check complete Facebook lead details
• UTM Tracking: View Campaign, AdSet, Ad information in Marketing section
• Lead Status: Regular leads, Organic leads, and Recaptured leads clearly marked

User Access Rights

• System Administrators: Full access to configuration and settings
• Sales Managers: Can configure forms and view all leads
• Sales Users: Can view and manage assigned leads
• HR Managers: Full access to recruitment applications
• Multi-Company: Users see only their company's data

Scheduled Actions

• Location: Settings → Technical → Automation → Scheduled Actions
• CRM Sync: "Fetch Facebook Leads (LucidBrainz)" runs every 1 hour
• HR Sync: "Fetch Facebook Recruitment (LucidBrainz)" runs every 1 hour
• Manual Run: Click "Run Manually" to sync immediately
• Customize: Adjust frequency from 1 hour to your preference