# Working with conversations

Working with LinkedIn conversations involves syncing a conversation once to retrieve its history, then polling it for new messages.

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

> 💡 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](/docs/monitoring-inbox).

## Syncing

Depending on the number of conversations you want to sync, [execute a workflow](/docs/executing-workflows) with one or multiple [`st.syncConversation`](/docs/action-st-sync-conversation) 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"
  }
]
```

**Completion:**

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

> 💡 For syncing conversations in **Sales Navigator**, use [`nv.syncConversation`](/docs/action-nv-sync-conversation) action.

## Polling

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

```text
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](/faq/what-are-hashed-url-and-public-url) 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": [
    {
      "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.
  - `threadId` – identifier of the conversation thread. Pass it to [`st.sendMessage`](/docs/action-st-send-message) / [`nv.sendMessage`](/docs/action-nv-send-message) 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](/docs/making-requests) 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).

> This page provides examples of [workflows](/docs/building-workflows) and their [completions](/docs/executing-workflows). For detailed documentation on constraints, parameters, and possible results of specific actions, always refer to the corresponding [action documentation pages](/docs/actions-overview).