inbox person view & one-time conversation history

Author: LordOfTheVillage

linkedapi/__init__.py

@@ -87,7 +87,7 @@
     verify_webhook_signature,
 )
 
-__version__ = "1.4.4"
+__version__ = "1.4.5"
 PredefinedOperation = Operation
 
 __all__ = [

linkedapi/client.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, overload
 from urllib.parse import urlencode
 
 from linkedapi.config import LinkedApiConfig
@@ -55,6 +55,8 @@
     ConversationPollRequest,
     ConversationPollResult,
     InboxMessage,
+    InboxPersonPollRequest,
+    InboxPersonPollResult,
     InboxPollRequest,
 )
 from linkedapi.types.network import NetworkEvent, NetworkPollRequest
@@ -161,7 +163,12 @@ def poll_conversations(
         self,
         conversations: list[ConversationPollRequest],
     ) -> MappedResponse[list[ConversationPollResult]]:
-        """Poll previously synced standard or Sales Navigator conversations."""
+        """Poll previously synced standard or Sales Navigator conversations.
+
+        Deprecated: legacy, kept working for existing integrations. Use ``poll_inbox`` with
+        ``InboxPersonPollRequest(person_url=...)``: it returns the same history together with the
+        messages the inbox captured, and does not fail for people whose history was never loaded.
+        """
 
         try:
             response = self.http_client.post("/conversations/poll", serialize_value(conversations))
@@ -187,15 +194,39 @@ def poll_conversations(
                 )
             raise
 
+    @overload
+    def poll_inbox(  # type: ignore[overload-overlap]
+        self,
+        request: InboxPersonPollRequest,
+    ) -> MappedResponse[InboxPersonPollResult]: ...
+
+    @overload
     def poll_inbox(
         self,
         request: InboxPollRequest | None = None,
-    ) -> MappedResponse[list[InboxMessage]]:
-        """Read the monitored standard or Sales Navigator inbox, newest messages first."""
+    ) -> MappedResponse[list[InboxMessage]]: ...
+
+    def poll_inbox(
+        self,
+        request: InboxPollRequest | None = None,
+    ) -> MappedResponse[list[InboxMessage]] | MappedResponse[InboxPersonPollResult]:
+        """Read the monitored standard or Sales Navigator inbox, newest messages first.
+
+        Without ``person_url`` the data is the list of inbox messages across every conversation.
+        With ``person_url`` (use ``InboxPersonPollRequest``) the data is the whole known
+        conversation with that person: the messages the inbox captured together with the history
+        loaded by ``sync_conversation`` / ``nv_sync_conversation``, each message once, plus
+        ``threads`` with ``history_from`` and ``history_complete``.
+        """
 
         payload = serialize_value(request) if request is not None else {}
         response = self.http_client.post("/inbox/poll", payload)
         if response.success and response.result is not None:
+            if request is not None and request.person_url:
+                return MappedResponse(
+                    data=InboxPersonPollResult.model_validate(response.result),
+                    errors=[],
+                )
             messages = response.result.get("messages", [])
             return MappedResponse(
                 data=[InboxMessage.model_validate(item) for item in messages],

linkedapi/types/__init__.py

@@ -112,6 +112,10 @@
     ConversationPollResult,
     ConversationType,
     InboxMessage,
+    InboxPersonMessage,
+    InboxPersonPollRequest,
+    InboxPersonPollResult,
+    InboxPersonThread,
     InboxPollRequest,
     ManageConversationParams,
     Message,
@@ -357,6 +361,10 @@
     "GetLimitsUsageParams",
     "IgnoreInvitationParams",
     "InboxMessage",
+    "InboxPersonMessage",
+    "InboxPersonPollRequest",
+    "InboxPersonPollResult",
+    "InboxPersonThread",
     "InboxPollRequest",
     "Invitation",
     "InvitationTargetParams",

linkedapi/types/message.py

@@ -2,6 +2,8 @@
 
 from typing import Literal
 
+from pydantic import Field
+
 from linkedapi.types.base import LinkedApiModel
 from linkedapi.types.params import BaseActionParams
 
@@ -90,6 +92,11 @@ class InboxPollRequest(LinkedApiModel):
     since: str | None = None
     type: ConversationType | None = None
     thread_id: str | None = None
+    person_url: str | None = None
+
+
+class InboxPersonPollRequest(InboxPollRequest):
+    person_url: str
 
 
 class InboxMessage(LinkedApiModel):
@@ -104,3 +111,20 @@ class InboxMessage(LinkedApiModel):
     sender: MessageSender | None = None
     text: str | None = None
     time: str | None = None
+
+
+class InboxPersonMessage(InboxMessage):
+    inbox_message_id: str | None = None
+
+
+class InboxPersonThread(LinkedApiModel):
+    thread_id: str | None = None
+    type: ConversationType | None = None
+    person_urn: str | None = None
+    history_from: str | None = None
+    history_complete: bool = False
+
+
+class InboxPersonPollResult(LinkedApiModel):
+    messages: list[InboxPersonMessage] = Field(default_factory=list)
+    threads: list[InboxPersonThread] = Field(default_factory=list)

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "linkedapi"
-version = "1.4.4"
+version = "1.4.5"
 description = "Official synchronous Python SDK for Linked API."
 readme = "README.md"
 requires-python = ">=3.10"

tests/test_direct_methods.py

@@ -6,6 +6,7 @@
 from linkedapi import (
     ApiUsageParams,
     ConversationPollRequest,
+    InboxPersonPollRequest,
     InboxPollRequest,
     LinkedApi,
     LinkedApiActionError,
@@ -108,6 +109,59 @@ def test_poll_inbox_success(fake_http_client: FakeHttpClient) -> None:
     assert result.errors == []
 
 
+def test_poll_inbox_with_person_url_returns_messages_and_threads(
+    fake_http_client: FakeHttpClient,
+) -> None:
+    linkedapi = LinkedApi(fake_http_client)
+    fake_http_client.queue_response(
+        result={
+            "messages": [
+                {
+                    "id": "h1",
+                    "inboxMessageId": None,
+                    "type": "st",
+                    "threadId": None,
+                    "personHashedUrl": "hashed",
+                    "sender": "them",
+                    "text": "hi",
+                    "time": "2026-01-01T10:00:00.000Z",
+                }
+            ],
+            "threads": [
+                {
+                    "threadId": None,
+                    "type": "st",
+                    "personUrn": "urn:li:member:1",
+                    "historyFrom": "2026-01-01T10:00:00.000Z",
+                    "historyComplete": True,
+                }
+            ],
+        }
+    )
+
+    result = linkedapi.poll_inbox(InboxPersonPollRequest(person_url="u", since="s"))
+
+    assert fake_http_client.calls[0] == ("POST", "/inbox/poll", {"since": "s", "personUrl": "u"})
+    assert result.data is not None
+    assert result.data.messages[0].inbox_message_id is None
+    assert result.data.messages[0].thread_id is None
+    assert result.data.threads[0].history_complete is True
+    assert result.data.threads[0].history_from == "2026-01-01T10:00:00.000Z"
+
+
+def test_poll_inbox_person_url_on_base_request_is_sent_not_dropped(
+    fake_http_client: FakeHttpClient,
+) -> None:
+    linkedapi = LinkedApi(fake_http_client)
+    fake_http_client.queue_response(result={"messages": [], "threads": []})
+
+    result = linkedapi.poll_inbox(InboxPollRequest(person_url="u"))
+
+    assert fake_http_client.calls[0] == ("POST", "/inbox/poll", {"personUrl": "u"})
+    assert result.data is not None
+    assert not isinstance(result.data, list)
+
+
 def test_poll_inbox_without_request_sends_empty_body(fake_http_client: FakeHttpClient) -> None:
     linkedapi = LinkedApi(fake_http_client)
     fake_http_client.queue_response(result={"messages": []})