pollInbox

This method polls your monitored inbox to retrieve captured messages and receive new ones across every conversation, for both standard and Sales Navigator inboxes.

Before polling, enable inbox monitoring once with syncInbox or nvSyncInbox.

typescript

try {
  const { data, errors } = await linkedapi.pollInbox({
    since: "2024-01-01T00:00:00Z", // Optional: only messages after this timestamp
    type: "st",                     // Optional: "st" | "nv"; omit for both
    threadId: "2-abc123..."         // Optional: restrict to a single thread
  });

  // The list of possible execution errors is below
  if (errors && errors.length > 0) {
    console.warn('Workflow completed with execution errors:');
    errors.forEach(error => {
      console.warn(` - Type: ${error.type}, Message: ${error.message}`);
    });
  }

  if (data) {
    console.log(`Retrieved ${data.messages.length} messages`);

    data.messages.forEach(message => {
      const sender = message.sender === 'us' ? 'You' : 'Them';
      console.log(`[${message.type}] ${sender} (${message.time}): ${message.text}`);
    });
  }
} catch (e) {
  // A list of all critical errors can be found here:
  // https://linkedapi.io/sdks/handling-results-and-errors/#handling-critical-errors
  if (e instanceof LinkedApiError) {
    console.error(`Critical Error - Type: ${e.type}, Message: ${e.message}`);
  } else {
    console.error('An unexpected, non-API error occurred:', e);
  }
}

python

from linkedapi import InboxPollRequest, LinkedApiError

try:
    result = linkedapi.poll_inbox(
        InboxPollRequest(
            since="2024-01-01T00:00:00Z",  # Optional: only messages after this timestamp
            type="st",                       # Optional: "st" | "nv"; omit for both
            thread_id="2-abc123...",        # Optional: restrict to a single thread
        )
    )
    data = result.data
    errors = result.errors

    # The list of possible execution errors is below
    if errors:
        print("Workflow completed with execution errors:")
        for error in errors:
            print(f" - Type: {error.type}, Message: {error.message}")

    if data:
        print(f"Retrieved {len(data.messages)} messages")

        for message in data.messages:
            sender = "You" if message.sender == "us" else "Them"
            print(f"[{message.type}] {sender} ({message.time}): {message.text}")
except LinkedApiError as e:
    # A list of all critical errors can be found here:
    # https://linkedapi.io/sdks/handling-results-and-errors/#handling-critical-errors
    print(f"Critical Error - Type: {e.type}, Message: {e.message}")
except Exception as error:
    print("An unexpected, non-API error occurred:", error)

Params

All fields are optional:

since – timestamp indicating the starting point for retrieving messages. If not provided, all captured messages are returned.
type – enum to filter by inbox type; omit for both:
- st – standard inbox messages only.
- nv – Sales Navigator inbox messages only.
threadId – restrict the result to a single conversation thread.

Data

messages – flat array of messages across all threads, ordered newest first.
- id – unique identifier for the message.
- type – inbox type the message belongs to (st or nv).
- threadId – identifier of the conversation thread. Pass it to sendMessage / nvSendMessage to reply into the thread.
- personUrn – URN of the other participant, or null if LinkedIn does not expose it.
- personHashedUrl – hashed LinkedIn URL of the other participant. This is the form the inbox exposes; every method that takes a person URL accepts it.
- personPublicUrl – public LinkedIn URL of the other participant, or null if it has not been resolved. It can be null on any message, including the first one in a thread.
- personUrl – deprecated, replaced by personHashedUrl, which carries the same value. Still returned so existing integrations keep working; do not use it in new code.
- sender – enum indicating who sent the message. Possible values:
  - us – message was sent by you (through the LinkedIn UI or the Linked API).
  - them – message was sent by the other person.
- text – message text.
- time – timestamp when the message was sent or received.

A person is resolved by the periodic sync, and only when their thread produces a message after monitoring was enabled by syncInbox. personPublicUrl is therefore null for everyone you have not heard from yet, and some people are never resolvable at all – so always handle null rather than assuming a message carries a public URL. Messages captured before this field existed, and people whose resolution did not succeed, stay null until that person sends another message or Linked API learns their public URL another way, for example through fetchPerson. personHashedUrl is always present and is the safe input for follow-up methods.

Recommended flow for integrations:

Leave since empty on the first request to retrieve everything captured so far.
For subsequent requests, pass the timestamp of the most recent message you received as since to fetch only newer messages.
Continue polling with an advancing since. Whenever new messages arrive, update since to the latest message time.

For push-based delivery instead of polling, subscribe to the inbox webhook events.

PreviouspollConversations NextpollNetwork