package google.home.graph.v1

Get desktop application:
View/edit binary Protocol Buffers messages

Google HomeGraph API. HomeGraph Service provides the support for storing and querying first-party and third-party devices, rooms and structures, the relationships among them and their state in the home. It stores entities and their relationships in the home.

• rpc DeleteAgentUser (DeleteAgentUserRequest, protobuf.Empty)

  homegraph.proto:73

  Unlink an agent user from Google. As result, all data related to this user will be deleted. Third-party user's identity is passed in as agent_user_id. Agent is identified by the JWT signed by the partner's service account. Note: Special characters (except "/") in agent_user_id must be URL encoded.

  message DeleteAgentUserRequest

  homegraph.proto:189

  Request type for DeleteAgentUser call.

  • string request_id = 1

    Request id used for debugging.

  • string agent_user_id = 2

    Required. Third-party user id.

• rpc ReportStateAndNotification (ReportStateAndNotificationRequest, ReportStateAndNotificationResponse)

  homegraph.proto:59

  Reports device state and optionally sends device notifications. Called by an agent when the device state of a third-party changes or the agent wants to send a notification about the device. This method updates a predefined set of States for a device, which all devices have (for example a light will have OnOff, Color, Brightness). A new State may not be created and an INVALID_ARGUMENT code will be thrown if so. It also optionally takes in a list of Notifications that may be created, which are associated to this State change. Third-party user's identity is passed in as agent_user_id. Agent is identified by the JWT signed by the partner's service account.

  message ReportStateAndNotificationRequest

  homegraph.proto:144

  Sample ReportStateAndNotificationRequest, with states and notifications defined per device_id (eg: "123" and "456" in the following example): { "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agent_user_id": "1234", "payload": { "devices": { "states": { "123": { "on": true }, "456": { "on": true, "brightness": 10 } }, "notifications": { "123": { "ObjectDetected": { "priority": 0, "objects": { "NAMED": ["Alice", "Bob", "Carol", "Eve"] } }, "DoorUnlocked": { "priority": 0, "keyUsed": { "keyName": "Wife's key" } } }, "456": { "SprinklersOn": { "priority": 0, "timeStarted": "1513792702" } } } } } } Request type for ReportStateAndNotification call. It may include States, Notifications, or both. This request uses globally unique flattened state names instead of namespaces based on traits to align with the existing QUERY and EXECUTE APIs implemented by 90+ Smart Home partners. Next tag: 5.

  • string request_id = 1

    Request id used for debugging.

  • string event_id = 4

    Unique identifier per event (eg: doorbell press).

  • string agent_user_id = 2

    Required. Third-party user id.

  • optional StateAndNotificationPayload payload = 3

    State of devices to update and notification metadata for devices. For example, if a user turns a light on manually, a State update should be sent so that the information is always the current status of the device. Notifications are independent from the state and its piece of the payload should contain everything necessary to notify the user. Although it may be related to a state change, it does not need to be. For example, if a device can turn on/off and change temperature, the states reported would include both "on" and "70 degrees" but the 3p may choose not to send any notification for that, or to only say that the "the room is heating up", keeping state and notification independent.

  message ReportStateAndNotificationResponse

  homegraph.proto:168

  Response type for ReportStateAndNotification call.

  • string request_id = 1

    Request id copied from ReportStateAndNotificationRequest.

• rpc RequestSyncDevices (RequestSyncDevicesRequest, RequestSyncDevicesResponse)

  homegraph.proto:41

  Requests a Sync call from Google to a 3p partner's home control agent for a user. Third-party user's identity is passed in as agent_user_id. (see [RequestSyncDevicesRequest][google.home.graph.v1.RequestSyncDevicesRequest]) and forwarded back to the agent. Agent is identified by the API key or JWT signed by the partner's service account.

  message RequestSyncDevicesRequest

  homegraph.proto:81

  Request type for RequestSyncDevices call.

  • string agent_user_id = 1

    Required. Third-party user id issued by agent's third-party identity provider.

  • bool async = 2

    Optional. If set, the request will be added to a queue and a response will be returned immediately. The queue allows for de-duplication of simultaneous requests.

  message RequestSyncDevicesResponse

  homegraph.proto:94

  Response type for RequestSyncDevices call. Intentionally empty upon success. An HTTP response code is returned with more details upon failure.

  (message has no fields)

The States and Notifications specific to a device.

Used in: StateAndNotificationPayload

• optional protobuf.Struct states = 1

  States of devices to update.

• optional protobuf.Struct notifications = 2

  Notifications metadata for devices.

Payload containing the State and Notification information for devices.

Used in: ReportStateAndNotificationRequest

• optional ReportStateAndNotificationDevice devices = 1

  The devices for updating State and sending Notifications.