Lead Capture

What lead capture covers

In this project, lead capture is not a single form submit event. It is the full system that receives inbound interest from social surfaces and connected sources, stores the incoming conversation context, optionally replies or extracts details with AI, and then converts accepted records into the main lead pipeline.

The codebase splits this into two layers. `SocialMediaLead` is the temporary record for captured social activity before workflow assignment, while `Lead` is the main workflow-ready record used for execution timing, recall state, status, and timeline history.

Capture sources

OrcaPulse already supports multiple inbound capture shapes across the project. The social integration model includes Facebook, Instagram, TikTok, Twitter, and LinkedIn platform records, while the product flow is centered around high-value inbound channels and form sources.

For social capture, the project tracks channel-specific origins such as comments, DMs, forms, story replies, story mentions, LinkedIn messages, and TikTok comments. LinkedIn lead capture also includes ad-account and lead-form selection metadata so form-based capture can be synced on a schedule or manually.

Capture settings

Each social integration has capture settings that control what enters the system and how the first response behaves. This is where teams decide whether to capture from comments, DMs, lead ads, story replies, or story mentions and whether the integration should reply automatically when trigger keywords appear.

The current model also exposes AI-specific options: extract contact information from raw conversation text, generate replies, and keep AI-driven DM conversations active when the integration should continue gathering details before human takeover.

• Auto-reply: Controlled by `autoReplyEnabled`, `autoReplyTemplate`, and trigger keyword configuration.
• AI extraction: `useAIForExtraction` stores parsed contact context and confidence on the social lead.
• AI reply and DM conversation: `useAIForReply` and `useAIForDMConversation` drive ongoing response behavior.
• Duplicate blocking: `preventDuplicates` can stop repeated records before they become main leads.

Capture pipeline

Once inbound activity is received, the project stores it on `SocialMediaLead` with platform identity, captured text, source type, optional extracted data, AI analysis, conversation history, and metadata such as page, post, form, or company fields. This record acts as the review layer before conversion.

If the lead is accepted, OrcaPulse converts it into the main `Lead` model and attaches workflow assignment. From that point on, the lead can move through execution timing, recall behavior, messaging, AI calls, CRM sync, webhook sync, and timeline updates.

Duplicates and conversion

Duplicate handling is a real part of the current product, not just a docs concept. The project has duplicate detection services for workflow leads, duplicate metadata on the main `Lead` model, and duplicate status handling on `SocialMediaLead`.

In the LinkedIn and social capture controllers, duplicate checks run before conversion when enough contact data is available. If a duplicate is detected, the social lead can be marked as duplicate and linked back to the existing lead. If not, the lead is converted and assigned to a workflow, with references stored on `convertedToLeadId` and `assignedToWorkflowId`.

• Social duplicate outcome: status can move to `duplicate` and preserve the existing lead link.
• Main lead duplicate outcome: duplicate metadata and timeline events can mark the record as skipped.
• Conversion output: converted leads become workflow-managed records with execution and status controls.

Operations and visibility

Operators already have two important places to review capture behavior in the app. `Social Media Leads` shows connected platforms, capture settings, sync actions, and captured social leads. `Lead Hub` shows the broader lead list across workflows once records are in the main system.

After conversion, timeline events give a structured audit trail for creation, assignment, delivery attempts, calls, transcripts, and status movement. This is how lead capture becomes observable after the initial intake event.

• Integration stats: total captured leads and per-source counters are stored on the integration record.
• Social review state: statuses like `new`, `replied`, `converted`, `duplicate`, and `invalid` help operators triage incoming capture.
• Main lead operations: execution status, recall state, duplicate history, and timeline events take over after conversion.

Next steps

After lead capture is connected, the next layer is deciding how captured records are qualified and routed. In practical setup terms, teams usually connect a capture source first, then move into workflow setup, qualification prompts, and downstream actions like CRM sync, webhook sync, messaging, or AI calling.

Use the portal to connect integrations and inspect incoming leads. Then continue with the workflow documentation so the captured records actually move into a production execution path.