Facebook Lead Processor

The FaceBookLeadProcessor.cs module handles lead ingestion from Facebook Lead Ads. This processor receives webhook notifications from Facebook, extracts lead data, performs deduplication checks, and routes leads either to AI Auto-Caller or to human telecallers based on system configuration.

Core Business Logic

Webhook Reception

Facebook sends lead data via HTTP POST webhook to a configured endpoint:

POST /api/webhooks/facebook-leads
Content-Type: application/json

The webhook payload contains:

Lead ID: Facebook lead identifier
Lead Gen Form ID: Which ad campaign generated the lead
Lead Data: Name, phone number, email, and additional fields
Timestamp: When the lead was generated

Lead Data Parsing

The processor extracts and normalizes lead information:

Field	Source	Usage
Full Name	`first_name` + `last_name`	Lead identification
Mobile Number	`phone_number` field	Deduplication & assignment
Email	`email` field	Contact method & CRM sync
Campaign ID	`lead_gen_form_id`	Maps to internal CallSource
Lead Gen Time	`created_time`	Timestamp for analytics

AI Routing Decision

The processor evaluates a routing configuration to determine lead destination:

Configuration Check: System setting EnableFacebookAIAutoCall or per-campaign setting
AI Route: If enabled, lead status set to Pending_AI_Call
- AI Auto-Caller (separate service) picks up and attempts call
- If AI succeeds, call outcome recorded
- If AI fails, lead falls back to staff assignment
Direct Staff Route: If disabled, normal assignment flow (same as external leads)

Duplicate Detection

Same 4-day mobile deduplication as external leads:

Query past 4 days for same mobile number
If found, assign to same staff
If not found, assign via round-robin or manager routing

CallSource Mapping

Facebook campaigns are mapped to internal CallSource records:

Facebook Lead Gen Form ID → CallSourceId
↓
Stores in: lead.CallSourceId
↓
Used for: Analytics, attribution, staff allocation rules

Webhook Processing Flow

Webhook Processing Sequence Diagram

Configuration Options

Routing Configuration

EnableFacebookAIAutoCall = true/false (global)
  OR
PerCampaignRouting:
  - Campaign_ID_1: AI_ROUTE
  - Campaign_ID_2: STAFF_ROUTE
  - Campaign_ID_3: MANAGER_ASSIGNMENT

Database Schema

Table	Field	Purpose
FacebookLeads	LeadId	Facebook lead identifier
FacebookLeads	StaffId	Assigned staff member
FacebookLeads	Mobile	Phone number
FacebookLeads	Email	Contact email
FacebookLeads	CallSourceId	Campaign reference
FacebookLeads	Status	Assigned, Pending_AI_Call, AI_Called, Completed
FacebookLeads	CreatedDate	Lead received timestamp
FacebookLeads	LastModified	Last status update

Error Handling

Webhook Failures

Scenario	Action
Invalid signature	Reject (401), log security alert
Malformed JSON	Reject (400), log parsing error
Database insert fails	Return 202 Accepted, retry with backoff
All staff unavailable	Assign to queue, notify manager

Fallback Behavior

AI Route Failure: Automatically fall back to available staff assignment
Staff Unavailable: Escalate to manager or hold in queue
Mobile Invalid: Log exception, require manual review

Performance Considerations

Webhook Timeout: Should complete within 5 seconds to avoid Facebook timeout
Asynchronous Processing: Move heavy operations (AI assignment) to background queue
Caching: Cache CallSource mappings and staff availability
Batching: If high volume, use message queue to batch leads

Integration Points

Facebook Lead Ads API: Webhook endpoint configuration
CallSource Mapping: Maps Facebook Form ID to internal CallSource
Deduplication Service: Shared with external leads processor
AI Auto-Caller Service: Consumes Pending_AI_Call leads
Staff Queue System: Assigns leads to human telecallers
Analytics Dashboard: Tracks Facebook lead metrics

Related Components

ExternalLeadBO: Handles non-Facebook external leads with same dedup logic
CallSourceBO: Maps campaigns to internal call sources
AI Auto-Caller Service: Processes AI-routed leads
Staff Service: Manages telecaller allocation

External Lead Assignment Call Source Mapping