--- title: LinkedIn subtitle: Understand how LinkedIn OAuth, Lead Gen Forms, sync, and conversational capture work in OrcaPulse slug: documentation/linkedin --- # LinkedIn This page documents how LinkedIn works in the current OrcaPulse project: OAuth connection, ad-account and Lead Gen form selection, scheduled lead syncing, social lead creation, LinkedIn comments and messages, AI-assisted reply flow, duplicate checks, and conversion into the main lead pipeline. ## What this LinkedIn integration covers LinkedIn is already implemented in two important ways in the current project. First, there is a dedicated Lead Gen Forms flow with ad-account selection, form selection, and recurring sync behavior. Second, there is a social activity path for LinkedIn comments and direct messages that can capture, reply, and collect contact details. That makes LinkedIn one of the richer channel pages in OrcaPulse because it spans both form-based demand capture and conversational follow-up. ## OAuth and integration setup LinkedIn starts with a real OAuth connection flow. The backend initiates auth, stores a state token for validation, exchanges the callback code for access tokens, loads the LinkedIn user profile, and saves the integration as an active social-media record. The saved integration is not only a token holder. It tracks display identity, token expiry, sync state, and metadata that later controls whether ad accounts and lead-gen forms have been loaded. - Validated OAuth: the connection flow uses a stored state value before accepting the callback. - Profile-backed integration: platform user ID, display name, username, picture, and token expiry are stored on the integration. - Metadata-aware setup: the integration record tracks whether ad accounts and lead-gen forms were loaded yet. ## Lead Gen form selection and syncing LinkedIn lead capture is not generic polling. The project includes a guided setup modal that first loads ad accounts, then loads Lead Gen forms for the selected account, and finally saves the chosen form back onto the integration record. After configuration, LinkedIn form responses are synced through a dedicated controller and cron path. This means the project already treats LinkedIn as a structured demand source with account-specific selection, not as a single flat inbox. - Ad-account selection: the front end loads ad accounts from LinkedIn before form selection is allowed. - Form selection: the chosen Lead Gen form ID is saved into integration metadata for later sync. - Polling model: LinkedIn Lead Gen Forms use sync and polling behavior rather than a fully realtime form webhook path. - Cron support: the backend already includes a recurring LinkedIn sync service for active integrations with selected forms. ## Social lead creation and duplicate control LinkedIn responses and conversations first land as social leads before becoming main leads. The social lead model stores platform identity, capture source, captured text, LinkedIn-specific metadata, conversation history, and intermediate status such as new, replied, duplicate, or converted. Duplicate checks are also part of the real LinkedIn flow. When email or phone is available, the project can compare that information against existing leads and stop duplicate creation before the same contact is converted twice. - Capture-source awareness: LinkedIn leads can come from forms, comments, or LinkedIn messages depending on the path. - Social-first storage: records start as social leads so the system can gather context before conversion. - Duplicate prevention: email and phone-based duplicate checks can mark a social lead as duplicate instead of creating a new main lead. - Status progression: LinkedIn records move through reply, duplicate, and converted states instead of being treated as one-step imports. ## Comments, messages, and AI reply flow Outside of Lead Gen Forms, the LinkedIn social controller also handles comments and direct messages. Comment capture checks trigger keywords before creating a lead, while message capture builds or continues a conversation history for that sender. AI-assisted responses are already tailored to LinkedIn tone. The reply prompts tell the model to stay professional, focus on collecting contact details, and adjust behavior for cases like missing info, completed capture, or duplicate detection. - Keyword-triggered comments: LinkedIn comments can create a lead only when the configured trigger words are present. - Threaded DM collection: LinkedIn messages append to conversation history while OrcaPulse gathers email and phone details. - AI or template replies: the system can send a simple template response or generate a professional AI reply for LinkedIn. - Contact extraction: incoming messages are parsed for email and phone before deciding whether to keep asking, convert, or stop. ## Conversion and workflow handoff Once LinkedIn has enough information, the social lead can convert into a main lead. That conversion is what brings the contact into the broader OrcaPulse lead operations system, including timelines, workflow assignment, and normal post-capture handling. This is why LinkedIn belongs in the same docs system as lead capture and routing: the channel-specific logic is only the front half of the pipeline, while the back half uses the shared lead and workflow infrastructure. - Main lead creation: LinkedIn records convert into the standard lead model once the right information is collected. - Timeline visibility: conversion events can be reflected in the same timeline system used by the rest of the product. - Workflow continuity: after conversion, LinkedIn leads can move through the same follow-up and routing logic as other channels. ## Next steps After LinkedIn, the next useful channel page is usually TikTok or Web Forms, depending on whether you want to keep documenting social channels first or cover direct website capture next.