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 RequestSyncDevices (, )
homegraph.proto:42Requests 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
homegraph.proto:118Request 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
homegraph.proto:131Response type for RequestSyncDevices call. Intentionally empty upon success. An HTTP response code is returned with more details upon failure.
(message has no fields)
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
homegraph.proto:179Sample ReportStateAndNotificationRequest, with states and notifications defined per device_id (eg: "123" and "456" in the following example): { "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "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: 6.
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.
string follow_up_token = 5
Token to maintain state in the follow up notification response.
optional 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
homegraph.proto:206Response type for ReportStateAndNotification call.
string request_id = 1
Request id copied from ReportStateAndNotificationRequest.
rpc DeleteAgentUser (, )
homegraph.proto:90Unlink an agent user from Google. As result, all data related to this user will be deleted. Here is how the agent user is created in Google: When users open their Google Home App, they can begin linking a 3p partner. User is guided through the OAuth process. After entering the 3p credentials, Google gets the 3p OAuth token, and uses it to make a Sync call to the 3p partner and gets back all the user's data, including agent_user_id and devices. Google then creates the agent user and stores a mapping from the agent_user_id -> Google ID mapping. Google also stores all user's devices under that Google ID. The mapping from agent_user_id -> Google ID is many to many, since one Google user can have multiple 3p accounts, and multiple Google users can map to one agent_user_id (e.g. husband and wife share one Nest account username/password). 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
homegraph.proto:227Request type for DeleteAgentUser call.
string request_id = 1
Request id used for debugging.
string agent_user_id = 2
Required. Third-party user id.
rpc Query (, )
homegraph.proto:99Gets the device states for the devices in QueryRequest. Third-party user's identity is passed in as agent_user_id. Agent is identified by the JWT signed by the third-party partner's service account.
message
homegraph.proto:240Request type for Query call. This should be the same format as the AoG action.devices.QUERY request (https://developers.google.com/actions/smarthome/create-app#actiondevicesquery) with the exception of the extra "agent_user_id" and no "intent" and "customData" field.
string request_id = 1
Request ID used for debugging.
string agent_user_id = 2
Required. Third-party user ID.
repeated inputs = 3
Required. Inputs containing third-party partner's device IDs for which to get the device states.
message
homegraph.proto:273Response type for Query call. This should follow the same format as AoG action.devices.QUERY response (https://developers.google.com/actions/smarthome/create-app#actiondevicesquery).
string request_id = 1
Request ID used for debugging. Copied from the request.
optional payload = 2
Device states for the devices given in the request.
rpc Sync (, )
homegraph.proto:109Gets all the devices associated with the given third-party user. Third-party user's identity is passed in as agent_user_id. Agent is identified by the JWT signed by the third-party partner's service account.
message
homegraph.proto:292Request type for Sync call. This should follow the same format as AoG action.devices.SYNC request (https://developers.google.com/actions/smarthome/create-app#actiondevicessync) with the exception of the extra "agent_user_id" and no "intent" field.
string request_id = 1
Request ID used for debugging.
string agent_user_id = 2
Required. Third-party user ID.
message
homegraph.proto:335Example SyncResponse: { "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "agentUserId": "1836.15267389", "devices": [{ "id": "123", "type": "action.devices.types.OUTLET", "traits": [ "action.devices.traits.OnOff" ], "name": { "defaultNames": ["My Outlet 1234"], "name": "Night light", "nicknames": ["wall plug"] }, "willReportState": false, "deviceInfo": { "manufacturer": "lights-out-inc", "model": "hs1234", "hwVersion": "3.2", "swVersion": "11.4" }, "customData": { "fooValue": 74, "barValue": true, "bazValue": "foo" } }] } } Response type for Sync call. This should follow the same format as AoG action.devices.SYNC response (https://developers.google.com/actions/smarthome/create-app#actiondevicessync).
string request_id = 1
Request ID used for debugging. Copied from the request.
optional payload = 2
Devices associated with the third-party user.
message
homegraph.proto:265Third-party partner's device ID for one device.
Used in:
string id = 1
Third-party partner's device ID.
message
device.proto:101Identifies a device in the third party or first party system.
Used in:
string agent_id = 1
The agent's ID. Generally it is the agent's AoG project id.
string device_id = 2
Device ID defined by the agent. The device_id must be unique.
message
device.proto:26Third-party partner's device definition.
Used in:
string id = 1
Third-party partner's device ID.
string type = 2
Hardware type of the device (e.g. light, outlet, etc).
repeated string traits = 3
Traits supported by the device.
optional name = 4
Name of the device given by the third party. This includes names given to the device via third party device manufacturer's app, model names for the device, etc.
bool will_report_state = 5
Indicates whether the state of this device is being reported to Google through ReportStateAndNotification call.
string room_hint = 6
If the third-party partner's cloud configuration includes placing devices in rooms, the name of the room can be provided here.
string structure_hint = 7
As in roomHint, for structures that users set up in the partner's system.
optional device_info = 8
Device manufacturer, model, hardware version, and software version.
optional attributes = 9
Attributes for the traits supported by the device.
string custom_data = 10
Custom JSON data provided by the manufacturer and attached to QUERY and EXECUTE requests in AoG.
repeated other_device_ids = 11
IDs of other devices associated with this device. This is used to represent a device group (e.g. bonded zone) or "facets" synced through different flows (e.g. Google Nest Hub Max with a Nest Camera). This may also be used to pass in alternate IDs used to identify a cloud synced device for local execution (i.e. local verification). If used for local verification, this field is synced from the cloud.
message
device.proto:86Device information.
Used in:
string manufacturer = 1
Device manufacturer.
string model = 2
Device model.
string hw_version = 3
Device hardware version.
string sw_version = 4
Device software version.
message
device.proto:73Different names for the device.
Used in:
string name = 1
Primary name of the device, generally provided by the user.
repeated string nicknames = 2
Additional names provided by the user for the device.
repeated string default_names = 3
List of names provided by the partner rather than the user, often manufacturer names, SKUs, etc.
message
homegraph.proto:253Device ID inputs to QueryRequest.
Used in:
optional payload = 1
Payload containing third-party partner's device IDs.
message
homegraph.proto:259Payload containing device IDs.
Used in:
repeated devices = 1
Third-party partner's device IDs to get device states for.
message
homegraph.proto:282Payload containing device states information.
Used in:
map<string, > devices = 1
States of the devices. Map of third-party device ID to struct of device states.
message
homegraph.proto:218The States and Notifications specific to a device.
Used in:
optional states = 1
States of devices to update.
optional notifications = 2
Notifications metadata for devices.
message
homegraph.proto:212Payload containing the State and Notification information for devices.
Used in:
optional devices = 1
The devices for updating State and sending Notifications.
message
homegraph.proto:344Payload containing device information.
Used in:
string agent_user_id = 1
Third-party user ID
repeated devices = 2
Devices associated with the third-party user.