--- title: Instagram subtitle: Understand how Instagram capture and conversation handling work in OrcaPulse slug: documentation/instagram --- # Instagram This page documents how Instagram works in the current OrcaPulse project: webhook-based capture, comments, DMs, story mentions, trigger-keyword logic, AI-guided conversations, duplicate checks, and conversion into workflow-managed leads. ## What this Instagram integration covers OrcaPulse already treats Instagram as a real inbound lead source, not just a future channel stub. The backend subscribes Instagram business accounts to webhook events, listens for changes and messaging events, and turns those interactions into social leads that can later be qualified and routed. In practice, the Instagram flow spans capture, reply behavior, AI conversation, duplicate protection, and conversion into the main lead pipeline. ## Instagram capture sources The current project already tracks multiple Instagram entry points. Comments can become leads, direct messages can open or continue a conversation record, and story mentions are also captured. The inbox layer also treats story-reply style interactions as part of the conversation set. This matters because Instagram is not handled as a single flat source. The project preserves how the lead actually arrived. - Comments: top-level comments can be captured while reply comments are skipped to reduce noise. - DMs: Instagram direct messages can create or continue a conversation-based social lead. - Story mentions: mentions can be captured as lead entries and handled like other social interactions. - Conversation continuity: repeated messages from the same user keep building conversation history instead of creating disconnected records. ## Webhooks, replies, and AI handling The Instagram integration is webhook-driven. The backend subscribes the connected account through the Facebook Graph flow, processes Instagram changes and messaging events, and then applies reply logic based on the integration settings. Reply behavior can be simple or more agentic. Trigger keywords can decide whether a comment should get an immediate reply, and DM flows can continue with AI-generated conversation handling rather than only a fixed canned response. - Trigger keywords: comment capture settings can detect important intent words and change reply behavior. - Comment replies: the project can answer on the comment thread itself instead of forcing everything into DMs. - AI DM conversations: DMs can keep collecting information through contextual replies built from conversation history. - Takeover path: once a conversation is taken over by a human, AI and auto-reply behavior can stop for that thread. ## Contact collection and duplicates Instagram conversations in OrcaPulse are not only for chat. The project uses the DM flow to collect contact information such as phone and email and then decide whether the lead should advance. Duplicate checks are already part of the Instagram path. If the system detects that the contact data already exists, the product can stop the flow from creating another routed lead and can send a duplicate-aware message instead. - Contact gathering: Instagram DMs can keep asking for missing phone and email details. - Extraction support: the backend already parses contact-like data from incoming text. - Duplicate protection: repeated Instagram leads can be blocked when the project finds an existing contact match. - Completion threshold: once enough contact information is present, the lead can move beyond the social-only state. ## Workflow conversion and routing Instagram lead capture eventually connects to the main OrcaPulse workflow engine. When a social lead is accepted, it can be converted into the main lead model, assigned to a workflow, and tracked through execution timing, follow-up, calls, CRM sync, webhook sync, and timeline history. This is what turns an Instagram comment or DM into an operational lead instead of leaving it as only a social conversation record. - Assigned workflow reference: social lead records store which workflow they were routed into. - Timeline support: assignment events make the Instagram-to-workflow handoff visible later. - Lead Hub path: after conversion, the lead can be managed from the broader lead operations surfaces. - Inbox continuity: teams can still review the original conversation context that led to routing. ## How to design the first Instagram launch The best first Instagram setup in this project is usually narrow. Start with one capture source, one clear contact-collection path, and one downstream workflow outcome instead of trying to automate every comment, DM, mention, and escalation case on day one. In most teams, that means starting with comments or DMs first, validating the trigger-keyword and reply behavior, and then adding richer AI conversation or routing logic after the initial flow is stable. - Pick one entry point first: comments or DMs are easier to test than every Instagram surface at once. - Keep the reply path simple: make sure auto-replies and AI replies are easy to review before scaling them. - Test duplicate cases: verify that existing contacts do not keep generating new lead records. - Confirm workflow handoff: check that successful Instagram conversations actually convert and route into the expected workflow. ## Next steps After Instagram is documented, the next channel page should usually be WhatsApp, because it has its own dedicated inbox, message model, templates, and account-level operational flow in the current project.