Rooms are the home

A room is the home’s display unit for people and apps: it has an icon, up to two tile actions, a listening setting, and a spoken announcement volume. The API returns resolved values for those fields, so clients do not need to guess at nulls. Room reads, room settings, room actions, discovery, deletion, merge, and move flows all center on what the room shows and how it affects the things inside it.

Room fields

The room model exposes these fields to the console and app:

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
announceVolume	How loud the assistant speaks in this room, on the speaker’s own 0-100 scale	The platform default, resolved when a line is played
primaryActions	Up to two [{ capability, action }] entries shown on the tile	The computed defaults: lights, then volume, then thermostat, then listening

GET /rooms/:id and the property overview return the resolved view. icon is never null, primaryActions are resolved, chosenActions remain as stored, and availableActions come from what the members report.

Tile values come from the API

Room tile values are calculated by the platform and shown by the client. actionValues on a room, and house.actionValues on the overview, carry each action’s aggregate value: any member on for a toggle, the members’ maximum for a number, and the room flag for listening. A client draws those values and does not compute its own figures.

Where rooms come from

Rooms can be created or discovered in two ways.

• Typed by a person. POST /rooms creates a room from a name and optional icon. GET /rooms/suggestions returns the list used by the add-a-room screen and the same list used for table discovery.
• Found on the network. POST /integrations/:id/discover with a propertyId places each newly found thing in the room named by the thing itself, creating the room if it does not exist, for any integration whose descriptor allows discovery. The home owner can start this from the home as “Look for new devices”. The console’s add-room sheet uses the same suggestion list for a room typed by hand. Discovery does not move a room that someone already placed and does not rename a room.

When a connector does not name a room, discovery looks at the thing’s own name and places it in an existing room whose name appears in that name. Matching is case-insensitive, uses letters and digits only, and the longest matching room name wins. If a provider uses words like bedroom or room, bath or bathroom, lounge or living room, or hall or entryway, discovery folds those synonyms before matching.

Removing and merging rooms

DELETE /rooms/:id removes the room and leaves its members in the home with no room, which unpairs them. The room settings screen warns about this before the button and names every affected member and the consequence.

Rooms can also be merged. In room merge mode, every room tile shows a checkbox, tile actions hide, the house tile stays out, and the UI prompts you to pick two or more rooms and choose which name to keep. Room settings also keep a single-room merge path. The merge operation moves every member into the room that stays, then deletes the merged room, one room at a time. If one step fails, later rooms do not continue merging.

Moving a thing between rooms

A thing’s own page has a room picker on both clients. Changing the pick saves at once and shows “Moving” then “Moved”. Only the thing page, the overview, the rooms screen, and the device list refresh; the whole cache does not need to reload. On Home, the room strip scrolls the selected tile into view.

Listening and announcement volume

listening controls wake-word detection for voice-capable devices in the room. It is a room fact, not a separate device toggle: a device moved into a silent room goes quiet with no second switch. The room setting and quiet hours are presented together, but they are not merged.

announceVolume belongs to the room because the speaker in the room is what makes the sound. The value is resolved in order: the say step’s own volume, then the room’s announceVolume, then the device paired to the room, then the platform default. A null value means “not chosen”, not zero and not 30. That matters because a default change reaches every room that never chose one.

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 for every room in the property. The response is per thing, with applied, skipped, or failed plus reasons. A voice or listening action sets the room flag. Members reached only through radio from the hub are reported as failed until room-action fan-out supports that transport.

Access boundaries

Any household member can see a room. Control access is narrower: any household membership can control commands, actions, and listening, and a GUEST can do so only inside the pinned property. Configuration is stricter: naming the room, choosing the icon, setting tile actions, and changing quiet hours or room settings require OWNER access.

Practical notes for developers

Room reads always return resolved values, so client code should treat null as a request for the platform default, not as an unknown. Discovery can create rooms when it places new things, but it never renames or rehomes things that a person already placed. Delete and merge operations change membership first or remove the room last, so client flows should reflect that order. When a thing changes rooms, only the relevant views need to refresh.