Working with conversations

Working with LinkedIn conversations involves 2 key steps:

1. Syncing. Each conversation needs to be synced once before you can work with it. This is a time-consuming process that retrieves conversation history from LinkedIn and prepares it for future updates.
2. Polling. After a conversation is synced, you can continuously poll it to get existing messages and receive new updates without needing to sync again.

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:

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

Completion:

[ 
  {
    "actionType": "st.syncConversation",
    "success": true
  },
  {
    "actionType": "st.syncConversation",
    "success": true
  }
]

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/account/conversations/poll

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

[
  {
    "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:

{
  "success": true,
  "result": [
    {
      "personUrl": "https://www.linkedin.com/in/person1",
      "since": "2023-01-01T00:00:00Z",
      "type": "st",
      "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"
        }
      ]
    },
    {
      "personUrl": "https://www.linkedin.com/in/person2",
      "since": "2023-01-04T00:00:00Z",
      "type": "nv",
      "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"
        }
      ]
    }
  ]
}

• messages – array of messages.
  • id – unique identifier for the message.
  • 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:

{
  "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:

1. Leave since empty to retrieve the full conversation history.
2. For subsequent requests, pass the timestamp of the last message you received as since to retrieve only new messages.
3. 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).