Working with conversations

Working with LinkedIn conversations involves 2 key steps:

Syncing. Each conversation needs to be synced before you can work with it. This is a time-consuming process that retrieves conversation history from LinkedIn and prepares it for future updates. Syncing lasts for a limited period — 30 days by default, up to 90.
Polling. While the syncing period lasts, you can continuously poll the conversation to get existing messages and receive new updates without needing to sync again. Once it ends, polling keeps returning everything collected so far, but new messages stop arriving until you sync the conversation again.

💡 This page covers watching specific people, including their full history. To monitor your entire inbox and react to any new incoming message without syncing people one by one, see Monitoring the inbox.

Syncing

Depending on the number of conversations you want to sync, execute a workflow with one or multiple st.syncConversation actions. Here's an example:

Workflow:

json

[ 
  {
    "actionType": "st.syncConversation",
    "personUrl": "https://www.linkedin.com/in/person1"
  },
  {
    "actionType": "st.syncConversation",
    "personUrl": "https://www.linkedin.com/in/person2",
    "days": 14
  }
]

Completion:

json

[ 
  {
    "actionType": "st.syncConversation",
    "success": true,
    "data": {
      "syncUntil": "2023-01-31T00:00:00Z"
    }
  },
  {
    "actionType": "st.syncConversation",
    "success": true,
    "data": {
      "syncUntil": "2023-01-15T00:00:00Z"
    }
  }
]

Pass days (1 to 90, 30 by default) to control how long the conversation stays synchronized. The period is counted from the moment the action starts running, and syncUntil in the completion tells you when it ends. Running the action again for the same person starts a new period and keeps the history already collected.

💡 For syncing conversations in Sales Navigator, use nv.syncConversation action.

Polling

Unlike syncing, you don't need to execute workflows to poll conversations. Instead, send a POST request to the following endpoint:

POST https://api.linkedapi.io/conversations/poll

In the request body, include an array of conversations you want to poll:

json

[
  {
    "personUrl": "https://www.linkedin.com/in/person1",
    "since": "2023-01-01T00:00:00Z",
    "type": "st"
  },
  {
    "personUrl": "https://www.linkedin.com/in/person2",
    "since": "2023-01-04T00:00:00Z",
    "type": "nv"
  }
]

personUrl – public or hashed LinkedIn URL of the person whose conversation you want to poll.
since (optional) – timestamp indicating the starting point for retrieving messages. If not provided, the entire conversation history will be returned.
type – enum indicating the conversation type:
- st – for standard conversations.
- nv – for Sales Navigator conversations.

If your request is correct, you will receive the following response:

json

{
  "success": true,
  "result": [
    {
      "personUrn": "urn:li:member:123456789",
      "personUrl": "https://www.linkedin.com/in/person1",
      "since": "2023-01-01T00:00:00Z",
      "type": "st",
      "syncUntil": "2023-01-31T00:00:00Z",
      "messages": [
        {
          "id": "f4d92946-8821-6da6-ff4c-c36f0671292a",
          "sender": "us",
          "text": "Hello, how are you?",
          "time": "2023-01-02T10:30:00Z"
        },
        {
          "id": "2a1b7f25-daba-5e20-70e9-c6427bb4f660",
          "sender": "them",
          "text": "I'm doing well, thanks for asking!",
          "time": "2023-01-02T10:35:00Z"
        }
      ]
    },
    {
      "personUrn": null,
      "personUrl": "https://www.linkedin.com/in/person2",
      "since": "2023-01-04T00:00:00Z",
      "type": "nv",
      "syncUntil": "2023-02-03T00:00:00Z",
      "messages": [
        {
          "id": "737e3d1c-15a8-6683-060f-5147eeb6ac26",
          "sender": "us",
          "text": "Hey! Are you available for a quick chat?",
          "time": "2023-01-03T09:00:00Z"
        },
        {
          "id": "a002c77f-e318-619a-b52f-6b629501e522",
          "sender": "them",
          "text": "Sure! Let me know when works for you.",
          "time": "2023-01-03T09:05:00Z"
        },
        {
          "id": "2b55d567-29e0-0632-2b21-ad2caf240bef",
          "sender": "us",
          "text": "How about this afternoon?",
          "time": "2023-01-03T09:10:00Z"
        }
      ]
    }
  ]
}

personUrn – URN of the person, or null if LinkedIn does not expose it.
syncUntil – moment when synchronization of this conversation stops. Once it is in the past, the messages below are still returned but no longer updated — sync the conversation again to resume updates.
messages – array of messages.
- id – unique identifier for the message.
- threadId – identifier of the conversation thread. Pass it to st.sendMessage / nv.sendMessage to reply directly into the thread. May be null for messages captured before a thread identifier was known.
- sender – enum indicating who sent the message. Possible values:
  - us – message was sent by you.
  - them – message was sent by the person.
- text – message text.
- time – timestamp when the message was sent or received.

In case of an unsuccessful request, you will receive the following response:

json

{
  "success": false,
  "error": {
    "type": "conversationsNotSynced",
    "message": "The conversations must be synced before polling: {conversations_list}."
  }
}

error – either a common error or the conversationsNotSynced error.

Recommended flow for integrations:

If you integrate this endpoint into a frontend application, we recommend the following approach:

Leave since empty to retrieve the full conversation history.
For subsequent requests, pass the timestamp of the last message you received as since to retrieve only new messages.
Continue using since to fetch new messages periodically. If new messages are returned, update the since timestamp to the latest message time.

This flow helps keep conversations up to date and allows your app to handle new message events (e.g., display notifications, play sounds, and so on).

This page provides examples of workflows and their completions. For detailed documentation on constraints, parameters, and possible results of specific actions, always refer to the corresponding action documentation pages.

PreviousSending Message NextMonitoring the Inbox