feat(web_api): add inbox message retrieval

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ximex

roborock/data/containers.py

@@ -328,6 +328,23 @@ class HomeDataScene(RoborockBase):
     name: str
 
 
+@dataclass
+class InboxMessage(RoborockBase):
+    """A single user/device inbox message (`/user/inbox`)."""
+
+    id: int | None = None
+    trigger: str | None = None
+    """Message category, e.g. NOTIFICATION, WARNING, SYSTEM, MARKETING, SHARE."""
+    duid: str | None = None
+    """Device this message relates to (None for account-level messages)."""
+    subject: str | None = None
+    content: str | None = None
+    extra: str | None = None
+    """Raw JSON string with action/templateId metadata."""
+    read: bool | None = None
+    create_time: str | None = None
+
+
 @dataclass
 class HomeDataSchedule(RoborockBase):
     id: int

roborock/web_api.py

@@ -15,7 +15,7 @@
 from pyrate_limiter import Duration, Limiter, Rate
 
 from roborock import HomeDataSchedule
-from roborock.data import HomeData, HomeDataRoom, HomeDataScene, ProductResponse, RRiot, UserData
+from roborock.data import HomeData, HomeDataRoom, HomeDataScene, InboxMessage, ProductResponse, RRiot, UserData
 from roborock.exceptions import (
     RoborockAccountDoesNotExist,
     RoborockException,
@@ -608,6 +608,42 @@ async def get_scenes(self, user_data: UserData, device_id: str) -> list[HomeData
         else:
             raise RoborockException("scene_response result was an unexpected type")
 
+    async def get_inbox_messages(
+        self,
+        user_data: UserData,
+        message_type: str = "NOTIFICATION",
+        device_id: str | None = None,
+        offset: int = 0,
+        limit: int = 20,
+    ) -> list[InboxMessage]:
+        """Get inbox messages of a given type, newest first.
+
+        ``message_type`` is one of NOTIFICATION/WARNING (device-scoped, require
+        ``device_id``) or SYSTEM/MARKETING/SHARE (account-scoped). rriot API host with
+        Hawk auth.
+        """
+        rriot = user_data.rriot
+        if rriot is None:
+            raise RoborockException("rriot is none")
+        if rriot.r.a is None:
+            raise RoborockException("Missing field 'a' in rriot reference")
+        path = "/user/inbox"
+        params = {"offset": str(offset), "limit": str(limit), "type": message_type}
+        if device_id is not None:
+            params["duid"] = device_id
+        inbox_request = PreparedRequest(
+            rriot.r.a,
+            self.session,
+            {
+                "Authorization": _get_hawk_authentication(rriot, path, params=params),
+            },
+        )
+        inbox_response = await inbox_request.request("get", path, params=params)
+        if not inbox_response or not inbox_response.get("success"):
+            raise RoborockException(inbox_response)
+        result = inbox_response.get("result") or {}
+        return [InboxMessage.from_dict(message) for message in result.get("list", [])]
+
     async def execute_scene(self, user_data: UserData, scene_id: int) -> None:
         rriot = user_data.rriot
         if rriot is None:

tests/fixtures/web_api_fixtures.py

@@ -137,6 +137,41 @@ def mock_rest_fixture(skip_rate_limit: Any, home_data: dict[str, Any]) -> aiores
             status=200,
             payload={"api": None, "code": 200, "result": None, "status": "ok", "success": True},
         )
+        mocked.get(
+            re.compile(r"https://.*roborock\.com/user/inbox(\?.*)?$"),
+            status=200,
+            payload={
+                "api": None,
+                "result": {
+                    "total": 2,
+                    "list": [
+                        {
+                            "id": 2458218464,
+                            "trigger": "NOTIFICATION",
+                            "duid": "abc123",
+                            "subject": "Roborock Q7",
+                            "content": "Battery low. Please charge.",
+                            "extra": '{"templateId":34}',
+                            "read": False,
+                            "createTime": "2026-05-29T14:03:16.542+00:00",
+                        },
+                        {
+                            "id": 2458212274,
+                            "trigger": "NOTIFICATION",
+                            "duid": "abc123",
+                            "subject": "Roborock Q7",
+                            "content": "Cleaning complete. Returning to dock.",
+                            "extra": '{"templateId":24}',
+                            "read": True,
+                            "createTime": "2026-05-23T06:08:39.687+00:00",
+                        },
+                    ],
+                },
+                "status": "ok",
+                "success": True,
+            },
+            repeat=True,
+        )
         mocked.post(
             re.compile(r"https://.*iot\.roborock\.com/api/v4/email/code/send.*"),
             status=200,

tests/test_web_api.py

@@ -81,6 +81,18 @@ async def test_get_scenes():
     ]
 
 
+async def test_get_inbox_messages():
+    """Test that we can fetch device inbox messages."""
+    api = RoborockApiClient(username="test_user@gmail.com")
+    ud = await api.pass_login("password")
+    messages = await api.get_inbox_messages(ud, "NOTIFICATION", device_id="abc123")
+    assert len(messages) == 2
+    assert messages[0].content == "Battery low. Please charge."
+    assert messages[0].read is False
+    assert messages[0].trigger == "NOTIFICATION"
+    assert messages[1].read is True
+
+
 async def test_execute_scene(mock_rest):
     """Test that we can execute a scene"""
     api = RoborockApiClient(username="test_user@gmail.com")