Package google.home.graph.v1

Index

HomeGraphApiService

Google Home Graph API service. The Home Graph service provides support for accessing first-party and third-party devices stored in Google's Home Graph. The Home Graph database provides contextual data about the relationships between devices and the home.

For more details, see the Home Graph developer guide.

DeleteAgentUser

rpc DeleteAgentUser(DeleteAgentUserRequest) returns (Empty)

Unlinks the given third-party user from your smart home Action. All data related to this user will be deleted.

For more details on how users link their accounts, see fulfillment and authentication.

The third-party user's identity is passed in via the agent_user_id (see DeleteAgentUserRequest). This request must be authorized using service account credentials from your Actions console project.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/homegraph

For more information, see the OAuth 2.0 Overview.
Query

rpc Query(QueryRequest) returns (QueryResponse)

Gets the current states in Home Graph for the given set of the third-party user's devices.

The third-party user's identity is passed in via the agent_user_id (see QueryRequest). This request must be authorized using service account credentials from your Actions console project.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/homegraph

For more information, see the OAuth 2.0 Overview.
ReportStateAndNotification

rpc ReportStateAndNotification(ReportStateAndNotificationRequest) returns (ReportStateAndNotificationResponse)

Reports device state and optionally sends device notifications. Called by your smart home Action when the state of a third-party device changes or you need to send a notification about the device. See Implement Report State for more information.

This method updates the device state according to its declared traits. Publishing a new state value outside of these traits will result in an INVALID_ARGUMENT error response.

The third-party user's identity is passed in via the agent_user_id (see ReportStateAndNotificationRequest). This request must be authorized using service account credentials from your Actions console project.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/homegraph

For more information, see the OAuth 2.0 Overview.
RequestSyncDevices

rpc RequestSyncDevices(RequestSyncDevicesRequest) returns (RequestSyncDevicesResponse)

Requests Google to send an action.devices.SYNC intent to your smart home Action to update device metadata for the given user.

The third-party user's identity is passed via the agent_user_id (see RequestSyncDevicesRequest). This request must be authorized using service account credentials from your Actions console project.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/homegraph

For more information, see the OAuth 2.0 Overview.
Sync

rpc Sync(SyncRequest) returns (SyncResponse)

Gets all the devices associated with the given third-party user.

The third-party user's identity is passed in via the agent_user_id (see SyncRequest). This request must be authorized using service account credentials from your Actions console project.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/homegraph

For more information, see the OAuth 2.0 Overview.

AgentDeviceId

Third-party device ID for one device.

Fields
id

string

Third-party device ID.

AgentOtherDeviceId

Alternate third-party device ID.

Fields
agent_id

string

Project ID for your smart home Action.
device_id

string

Unique third-party device ID.

DeleteAgentUserRequest

Request type for the DeleteAgentUser call.

Fields
request_id

string

Request ID used for debugging.
agent_user_id

string

Required. Third-party user ID.

Device

Third-party device definition. Next ID = 14

Fields
id

string

Third-party device ID.
type

string

Hardware type of the device. See device types.
traits[]

string

Traits supported by the device. See device traits.
name

DeviceNames

Names given to this device by your smart home Action.
will_report_state

bool

Indicates whether your smart home Action will report state of this device to Google via ReportStateAndNotification.
room_hint

string

Suggested name for the room where this device is installed. Google attempts to use this value during user setup.
structure_hint

string

Suggested name for the structure where this device is installed. Google attempts to use this value during user setup.
device_info

DeviceInfo

Device manufacturer, model, hardware version, and software version.
attributes

Struct

Attributes for the traits supported by the device.
custom_data

Struct

Custom device attributes stored in Home Graph and provided to your smart home Action in each QUERY and EXECUTE intent. Data in this object has a few constraints: No sensitive information, including but not limited to Personally Identifiable Information.
other_device_ids[]

AgentOtherDeviceId

Alternate IDs associated with this device. This is used to identify cloud synced devices enabled for local fulfillment.
notification_supported_by_agent

bool

Indicates whether your smart home Action will report notifications to Google for this device via ReportStateAndNotification.

If your smart home Action enables users to control device notifications, you should update this field and call RequestSyncDevices.

DeviceInfo

Device information.

Fields
manufacturer

string

Device manufacturer.
model

string

Device model.
hw_version

string

Device hardware version.
sw_version

string

Device software version.

DeviceNames

Identifiers used to describe the device.

Fields
name

string

Primary name of the device, generally provided by the user.
nicknames[]

string

Additional names provided by the user for the device.
default_names[]

string

List of names provided by the manufacturer rather than the user, such as serial numbers, SKUs, etc.

QueryRequest

Request type for the Query call.

Fields
request_id

string

Request ID used for debugging.
agent_user_id

string

Required. Third-party user ID.
inputs[]

QueryRequestInput

Required. Inputs containing third-party device IDs for which to get the device states.

QueryRequestInput

Device ID inputs to QueryRequest.

Fields
payload

QueryRequestPayload

Payload containing third-party device IDs.

QueryRequestPayload

Payload containing device IDs.

Fields
devices[]

AgentDeviceId

Third-party device IDs for which to get the device states.

QueryResponse

Response type for the Query call. This should follow the same format as the Google smart home action.devices.QUERY response.

Example:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true
      },
      "456": {
        "on": true,
        "online": true,
        "brightness": 80,
        "color": {
          "name": "cerulean",
          "spectrumRGB": 31655
        }
      }
    }
  }
}
Fields
request_id

string

Request ID used for debugging. Copied from the request.
payload

QueryResponsePayload

Device states for the devices given in the request.

QueryResponsePayload

Payload containing device states information.

Fields
devices

map<string, Struct>

States of the devices. Map of third-party device ID to struct of device states.

ReportStateAndNotificationDevice

The states and notifications specific to a device.

Fields
states

Struct

States of devices to update. See the Device STATES section of the individual trait reference guides.
notifications

Struct

Notifications metadata for devices. See the Device NOTIFICATIONS section of the individual trait reference guides.

ReportStateAndNotificationRequest

Request type for the ReportStateAndNotification call. It may include states, notifications, or both. States and notifications are defined per device_id (for example, "123" and "456" in the following example).

Example:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "1234",
  "payload": {
    "devices": {
      "states": {
        "123": {
          "on": true
        },
        "456": {
          "on": true,
          "brightness": 10
        }
      },
    }
  }
}
Fields
request_id

string

Request ID used for debugging.
event_id

string

Unique identifier per event (for example, a doorbell press).
agent_user_id

string

Required. Third-party user ID.
follow_up_token
(deprecated)

string

Deprecated.
payload

StateAndNotificationPayload

Required. State of devices to update and notification metadata for devices.

ReportStateAndNotificationResponse

Response type for the ReportStateAndNotification call.

Fields
request_id

string

Request ID copied from ReportStateAndNotificationRequest.

RequestSyncDevicesRequest

Request type for the RequestSyncDevices call.

Fields
agent_user_id

string

Required. Third-party user ID.
async

bool

Optional. If set, the request will be added to a queue and a response will be returned immediately. This enables concurrent requests for the given agent_user_id, but the caller will not receive any error responses.

RequestSyncDevicesResponse

Response type for the RequestSyncDevices call.

Intentionally empty upon success. An HTTP response code is returned with more details upon failure.

StateAndNotificationPayload

Payload containing the state and notification information for devices.

Fields
devices

ReportStateAndNotificationDevice

The devices for updating state and sending notifications.

SyncRequest

Request type for the Sync call.

Fields
request_id

string

Request ID used for debugging.
agent_user_id

string

Required. Third-party user ID.

SyncResponse

Response type for the Sync call. This should follow the same format as the Google smart home action.devices.SYNC response.

Example:

{
  "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"
      }
    }]
  }
}
Fields
request_id

string

Request ID used for debugging. Copied from the request.
payload

SyncResponsePayload

Devices associated with the third-party user.

SyncResponsePayload

Payload containing device information.

Fields
agent_user_id

string

Third-party user ID
devices[]

Device

Devices associated with the third-party user.