Retrieving conversations

This page explains how to retrieve LinkedIn conversations through two separate channels: the standard messaging channel and Sales Navigator.

Retrieving conversations involves two key steps:

1. Synchronization. Conversations must be synchronized before you can retrieve messages from them. This is a time-consuming process, as it fetches conversations from LinkedIn and prepares them for further updates.
2. Retrieval. After synchronization, you can retrieve messages from the synchronized conversations and check for updates – all with near-instant response times.

Synchronization

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

Body

{
  "standard": [
    {
      "person": "https://www.linkedin.com/in/person1"
    },
    {
      "person": "https://www.linkedin.com/in/person2"
    }
  ],
  "salesNavigator": [
    {
      "person": "https://www.linkedin.com/in/person3"
    }
  ]
}

• standard – array of standard conversations.
• salesNavigator – array of Sales Navigator conversations.
• person – LinkedIn URL of the person whose conversation you want to synchronize.

Response

1. If all conversations are successfully synchronized:

{
  "status": "complete",
  "completion": {
    "standard": [
      {
        "person": "https://www.linkedin.com/in/person1",
        "result": {
          "success": true
        }
      },
      {
        "person": "https://www.linkedin.com/in/person2",
        "result": {
          "success": true
        }
      }
    ],
    "salesNavigator": [
      {
        "person": "https://www.linkedin.com/in/person3",
        "result": {
          "success": true
        }
      }
    ]
  }
}

2. If some conversations are not synchronized:

{
  "status": "complete",
  "completion": {
    "standard": [
      {
        "person": "https://www.linkedin.com/in/person1",
        "result": {
          "success": true
        }
      },
      {
        "person": "https://www.linkedin.com/in/person2",
        "result": {
          "success": false,
          "error": {
            "errorType": "personNotFound"
            "message": "The provided URL is not an existing LinkedIn person."
          }
        }
      }
    ],
    "salesNavigator": [
      {
        "person": "https://www.linkedin.com/in/person3",
        "result": {
          "success": true
        }
      }
    ]
  }
}

• errorType – enum with the following possible values:
  • personNotFound – provided URL is not an existing LinkedIn person.

Retrieval

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

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.