Rooms are the home

Rooms are the home’s main organizing unit. A room has an icon, a listening flag, and up to two primary tile actions. The API returns the resolved room view, so a client sees the icon, the room’s chosen and available actions, and the tile values that belong on the screen. Rooms also control whether voice-capable devices in that room listen for a wake word, and that setting is separate from quiet hours. The house keeps working when the cloud is down, and a household sees less than staff; DEV keys act in a sandbox, while a LIVE key only works for its own connector.

Room fields

Field	Meaning	Null means
icon	a token from ROOM_ICONS	the default for the room name, resolved at read time
listening	whether voice-capable devices in the room listen for a wake word	defaults true
primaryActions	up to two [{ capability, action }] entries shown on the room tile	the computed defaults: lights, then volume, then thermostat, then listening

GET /rooms/:id and the property overview return the resolved view. In that view, icon is never null. primaryActions are resolved, which means a chosen action the room can no longer serve is dropped. The response also includes chosenActions as stored and availableActions from what the members report.

What the room tile shows

A room tile shows values taken from the API. actionValues on a room, and house.actionValues on the overview, carry each action’s aggregate value. For a toggle, the value is any member on. For a number, it is the members’ maximum. For listening, it is the room flag. The client draws these values and does not compute them on its own.

Where rooms come from

Rooms enter the house in two ways.

• A person creates one with POST /rooms, using a name and an optional icon.
• Discovery places things and may create rooms when needed with POST /integrations/:id/discover and a propertyId, for any integration whose descriptor declares discovery.

The add-a-room screen uses GET /rooms/suggestions, and the same list is used for discovery. If discovery finds a thing whose room is missing, it places the thing in the room of its name and creates that room if needed. It never moves a thing that a person already placed, and it never renames a room.

If discovery names no room, the thing’s own name can place it in an existing room whose name appears inside it. The match ignores case, uses letters and digits only, and prefers the longest room name when several match. If a connector names room synonyms, those words are folded before matching.

Removing a room

DELETE /rooms/:id leaves the members in the house but with no room. That unpairs them from the room. Room settings explain this before the button appears, including the members that will be affected and the result.

Listening and quiet hours

Listening and quiet hours are separate gates on separate directions.

Setting	Gates	Direction	What it affects
listening	wake-word detection	what the house hears	platform to home-agent config to voice API projection to the hub microphone mute switch
quiet hours	speaking and update reboots	what the house says	quiet-hours rules

They appear together in room settings, but they are not merged. Listening is a room fact, so a device moved into a silent room goes quiet with no second switch.

The device reports back when the physical mute switch changes. That state is relayed through POST /state, stored, and shown on the hub as voice.micMuted and voice.listening. A button press on the device is visible, and it is never overridden; the system only commands the switch when the room’s choice changes.

A change to PATCH /rooms/:id { listening: false } makes the hub report muted within seconds, and the state returns as thing.state with voice.micMuted: true and voice.listening: false. The reverse also happens. Propagation follows the agent sync and the voice projection loop, which can take up to 60 seconds unless triggered.

Room actions

POST /rooms/:id/actions { capability, action, value } resolves the members when it runs and fans out to them. POST /properties/:id/actions does the same across the property. The response is per thing, with applied, skipped, or failed and reasons. voice and listening set the room flag. Members reached only through the hub’s radio are reported as failed until the later platform support exists.

Rights

Any member can see the house.

To control a room, including commands, actions, and listening, any membership is enough, but a GUEST can do that only inside the pinned property.

To configure a room, including name, icon, tile actions, quiet hours, and settings, OWNER is required.

Renaming, merging, and moving

A thing can be renamed where it is seen: on Home, on Devices, on its page, and on the landed row of the add sheet. A connector’s rediscovery never renames.

Rooms can be merged when a provider creates duplicates. Home offers a merge mode from the room strip, and room settings keep a single-room path for merging into another room. The merge keeps one room name, moves all members to the room kept, then removes the merged room. If one step fails, later rooms do not continue.

A thing’s room can also be changed from the thing’s page with the room picker. The pick updates at once and the page shows “Moving” and then “Moved”. Only the thing, the overview, the rooms list, and the device list refresh.

What a developer should expect

Rooms are both the organizing page and the home tile model. A client should read the resolved room view, use the API-provided action values, and treat listening as a room-level state that affects what the house hears. When deleting, the members stay in the house and lose their room. When moving or merging, the room changes are visible through the room list, the overview, and the thing pages, not through hidden client-side calculations.