Working with conversations

Working with LinkedIn conversations involves 2 key steps:

1. Syncing. Conversations must be synced before you can work with them. This is a time-consuming process, as it retrieves conversations from LinkedIn and prepares them for further updates.
2. Polling. After conversations have been synced, you can continuously poll them to get existing messages and receive new updates.

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",
    "label": "sync1"
  },
  {
    "actionType": "st.syncConversation",
    "personUrl": "https://www.linkedin.com/in/person2",
    "label": "sync2"
  },
  {
    "actionType": "st.syncConversation",
    "personUrl": "https://www.linkedin.com/in/person3",
    "label": "sync3"
  }
]

Completion:

[ 
  {
    "actionType": "st.syncConversation",
    "success": true,
    "label": "sync1"
  },
  {
    "actionType": "st.syncConversation",
    "success": true,
    "label": "sync2"
  },
  {
    "actionType": "st.syncConversation",
    "success": true,
    "label": "sync3"
  }
]

Polling

To synce

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

Body:

{
  "standard": [
    {
      "person": "https://www.linkedin.com/in/person1",
      "since": "2023-01-01T00:00:00Z"
    },
    {
      "person": "https://www.linkedin.com/in/person2",
    }
  ],
  "salesNavigator": [
    {
      "person": "https://www.linkedin.com/in/person3",
      "since": "2023-01-01T00:00:00Z"
    }
  ]
}

• standard – array of standard conversations.
• salesNavigator – array of Sales Navigator conversations.
• person – LinkedIn URL of the person whose conversation you want to retrieve.
• since (optional) – timestamp indicating the starting point for retrieving messages. If not provided, the entire conversation history will be returned.

Recommended flow for using since:

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).

Response

1. If all conversations are successfully retrieved:

{
  "status": "complete",
  "completion": {
    "standard": [
      {
        "person": "https://www.linkedin.com/in/person1",
        "result": {
          "success": true,
          "data": {
            "total": 2,
            "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"
              }
            ]
          }
        }
      },
      {
        "person": "https://www.linkedin.com/in/person2",
        "result": {
          "success": true,
          "data": {
            "total": 3,
            "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"
              }
            ]
          }
        }
      }
    ],
    "salesNavigator": [
      {
        "person": "https://www.linkedin.com/in/person3",
        "result": {
          "success": true,
          "data": {
            "total": 2,
            "messages": [
              {
                "id": "036be8c7-c205-2a32-6e48-95f2735ea89c",
                "sender": "them",
                "text": "Hi! I saw your profile and wanted to connect.",
                "time": "2023-01-04T11:15:00Z"
              },
              {
                "id": "c9066a7e-5698-dd05-cf8e-aae15d5e7439",
                "sender": "us",
                "text": "Thanks for reaching out! Let's connect.",
                "time": "2023-01-04T11:20:00Z"
              }
            ]
          }
        }
      }
    ]
  }
}

• total – total number of messages retrieved in the conversation.
• id – unique identifier for the message.
• sender – enum indicating who sent the message. Possible values:
  • us – message was sent by your LinkedIn account.
  • them – message was sent by the person whose conversation you retrieved.
• text – message text.
• time – timestamp when the message was sent or received.

2. If some conversations are not retrieved:

{
  "status": "complete",
  "completion": {
    "standard": [
      {
        "person": "https://www.linkedin.com/in/person1",
        "result": {
          "success": true,
          "data": {
            "total": 2,
            "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"
              }
            ]
          }
        }
      },
      {
        "person": "https://www.linkedin.com/in/person2",
        "result": {
          "success": false,
          "error": {
            "errorType": "notSynchronized"
            "message": "The conversation with this person isn't synchronized."
          }
        }
      }
    ],
    "salesNavigator": [
      {
        "person": "https://www.linkedin.com/in/person3",
        "result": {
          "success": false,
          "error": {
            "errorType": "notSynchronized"
            "message": "The conversation with this person isn't synchronized."
          }
        }
      }
    ]
  }
}

• errorType – enum with the following possible values:
  • notSynchronized – the conversation with this person isn't synchronized.