🔗 Connection → Lead Generating Message Sequence (LinkedIn Only)

This flow describes how to generate leads using Salesflow API through LinkedIn by automating:

1. Sending a connection request

2. Detecting when the connection is accepted

3. Sending follow-up messages

4. Receiving replies

5. Marking a lead

Prerequisites

• Ensure the LinkedIn account is onboarded via the iFrame flow.

• You have a valid X-AccountId header for all API requests.

• Webhooks for New Connection and New Message are configured.

High-Level Flow

1. Send the connection request (with or without a note).
   👉 https://salesflow.apidocumentation.com/documentation/messaging-chats/send-connection-request

2. Detect acceptance of the invite.
   👉 https://salesflow.apidocumentation.com/documentation/webhooks-triggers/new-connection

3. Deliver the first message based on how you sent the invite:

   • Invite without a message: send a regular follow-up. If no conversation exists, create one.
     👉 https://salesflow.apidocumentation.com/documentation/messaging-chats/send-regular-message-follow-up (Create a new conversation)

   • Invite with a message: first sync to get the conversationId, then send to the existing conversation.

     • Prefer Inbox Sync (walks newest → down to your last stored date).

     • Note: Specific Conversation Sync currently returns the entire thread; use it only if you actually need full history.
       👉 Sync: https://salesflow.apidocumentation.com/documentation/messaging-chats/sync-inbox-or-specific-conversation
       👉 Send: https://salesflow.apidocumentation.com/documentation/messaging-chats/send-regular-message-follow-up (Send to an existing conversation)

4. (Recommended) Sync again to refresh the thread and track replies.
   👉 https://salesflow.apidocumentation.com/documentation/messaging-chats/sync-inbox-or-specific-conversation

Step-by-Step

1) Send the connection request

Choose with/without note.
🔗 https://salesflow.apidocumentation.com/documentation/messaging-chats/send-connection-request

Notes

• Use an idempotency key on your side to avoid duplicates.

• Respect daily limits (see LinkedIn Limits).

2) Detect acceptance

Handle the New Connection webhook in your backend.
🔗 https://salesflow.apidocumentation.com/documentation/webhooks-triggers/new-connection

You’ll know:

• The newly connected profile IDs/metadata.

• It’s OK to proceed to messaging.

3) First message (branch)

A) Invite was sent without a message
Send a regular follow-up. If there’s no conversation yet, create one.
🔗 https://salesflow.apidocumentation.com/documentation/messaging-chats/send-regular-message-follow-up

B) Invite was sent with a message
Run a Sync to get the conversationId, then send to the existing conversation.

• Prefer Inbox Sync (newest → down to your last stored date) to discover the conversation efficiently.

• Note: Specific Conversation Sync returns the full thread; call it only if you need the entire history (heavier operation).
  🔗 Sync: https://salesflow.apidocumentation.com/documentation/messaging-chats/sync-inbox-or-specific-conversation
  🔗 Send to existing conversation: https://salesflow.apidocumentation.com/documentation/messaging-chats/send-regular-message-follow-up

4) Keep state fresh

After sending, sync again (newest → down to your last stored date) to update message state and detect replies.
🔗 https://salesflow.apidocumentation.com/documentation/messaging-chats/sync-inbox-or-specific-conversation

Sync Best Practices (important)

Inbox Sync

• Runs top-down: starts from the newest conversations/messages and continues backward in time until the “last processed date” you provide.

• Store your last processed timestamp (UTC) per account (optionally per conversation). Example:

  { "lastSyncedAtUtc": "2025-08-12T10:15:00Z" }

  json

• On each sync request, include this timestamp as your “until” value (see request fields on the Sync page).

• Use a small overlap window for safety (e.g., until = lastSyncedAtUtc - 1–2 minutes).

• Update your marker only after sync finished to avoid missing late arrivals.

Specific Conversation Sync

• Currently returns the entire conversation (from the first message to the latest).

• There’s no partial windowing by date for this call.

• Use it sparingly (e.g., initial hydration after acceptance with a note, or when you truly need full history).

• For ongoing updates and UI refreshes prefer Inbox Sync; on your side, dedupe by the last seen message ID/timestamp.

Typical Timeline (example)

1. T0 — Send connection request (with/without note).

2. T+? — Receive New Connection webhook.

3. Then:

   • If no note: send follow-up (create conversation if needed).

   • If with note: Inbox Sync (newest → until last stored date) → get conversationId → send to existing conversation.
     (Use Specific Conversation Sync only if full history is required.)

4. T+5–10 min: Inbox Sync again to refresh message state; repeat as needed.

Common Pitfalls & Fixes

• Expecting a partial window for Specific Conversation Sync.
  Not supported now — it always returns the full thread; use Inbox Sync for incremental updates.

• No conversationId after acceptance.
  Expected for invites without a note — use the create new conversation flow.

• Missing replies.
  Schedule periodic Inbox Syncs and track your last sync timestamp with a small overlap.