# Package google.home.graph.v1

## Index

- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService` (interface)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.AgentDeviceId` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.AgentOtherDeviceId` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.DeleteAgentUserRequest` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.Device` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.DeviceInfo` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.DeviceNames` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.QueryRequest` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.QueryRequestInput` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.QueryRequestPayload` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.QueryResponse` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.QueryResponsePayload` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.ReportStateAndNotificationDevice` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.ReportStateAndNotificationRequest` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.ReportStateAndNotificationResponse` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.RequestSyncDevicesRequest` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.RequestSyncDevicesResponse` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.StateAndNotificationPayload` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.SyncRequest` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.SyncResponse` (message)
- `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.SyncResponsePayload` (message)

## 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](https://developers.home.google.com/cloud-to-cloud/primer/home-graph).

| DeleteAgentUser |
|---|
| `` rpc DeleteAgentUser(`https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.DeleteAgentUserRequest`) returns (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.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](https://developers.home.google.com/cloud-to-cloud/primer/fulfillment). The third-party user's identity is passed in via the `agent_user_id` (see `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.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](https://developers.google.com/identity/protocols/OAuth2). |

| Query |
|---|
| `` rpc Query(`https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.QueryRequest`) returns (`https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.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 `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.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](https://developers.google.com/identity/protocols/OAuth2). |

| ReportStateAndNotification |
|---|
| `` rpc ReportStateAndNotification(`https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.ReportStateAndNotificationRequest`) returns (`https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.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](https://developers.home.google.com/cloud-to-cloud/integration/report-state) for more information. This method updates the device state according to its declared [traits](https://developers.home.google.com/cloud-to-cloud/primer/device-types-and-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 `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.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](https://developers.google.com/identity/protocols/OAuth2). |

| RequestSyncDevices |
|---|
| `` rpc RequestSyncDevices(`https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.RequestSyncDevicesRequest`) returns (`https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.RequestSyncDevicesResponse`) `` Requests Google to send an `action.devices.SYNC` [intent](https://developers.home.google.com/cloud-to-cloud/intents/sync) 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 `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.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](https://developers.google.com/identity/protocols/OAuth2). |

| Sync |
|---|
| `` rpc Sync(`https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.SyncRequest`) returns (`https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.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 `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.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](https://developers.google.com/identity/protocols/OAuth2). |

## 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`](https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService.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](https://developers.home.google.com/cloud-to-cloud/guides). |
| `traits[]` | `string` Traits supported by the device. See [device traits](https://developers.home.google.com/cloud-to-cloud/traits). |
| `name` | `` `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.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 `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService.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` | `` `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.DeviceInfo` `` Device manufacturer, model, hardware version, and software version. |
| `attributes` | `` `https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Struct` `` Attributes for the traits supported by the device. |
| `custom_data` | `` `https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Struct` `` Custom device attributes stored in Home Graph and provided to your smart home Action in each [QUERY](https://developers.home.google.com/cloud-to-cloud/intents/query) and [EXECUTE](https://developers.home.google.com/cloud-to-cloud/intents/execute) intent. Data in this object has a few constraints: No sensitive information, including but not limited to Personally Identifiable Information. |
| `other_device_ids[]` | `` `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.AgentOtherDeviceId` `` Alternate IDs associated with this device. This is used to identify cloud synced devices enabled for [local fulfillment](https://developers.home.google.com/local-home/overview). |
| `notification_supported_by_agent` | `bool` Indicates whether your smart home Action will report notifications to Google for this device via `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService.ReportStateAndNotification`. If your smart home Action enables users to control device notifications, you should update this field and call `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService.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`](https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService.Query) call.

| Fields ||
|---|---|
| `request_id` | `string` Request ID used for debugging. |
| `agent_user_id` | `string` Required. Third-party user ID. |
| `inputs[]` | `` `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.QueryRequestInput` `` Required. Inputs containing third-party device IDs for which to get the device states. |

## QueryRequestInput

Device ID inputs to `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.QueryRequest`.

| Fields ||
|---|---|
| `payload` | `` `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.QueryRequestPayload` `` Payload containing third-party device IDs. |

## QueryRequestPayload

Payload containing device IDs.

| Fields ||
|---|---|
| `devices[]` | `` `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.AgentDeviceId` `` Third-party device IDs for which to get the device states. |

## QueryResponse

Response type for the [`Query`](https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService.Query) call. This should follow the same format as the Google smart home `action.devices.QUERY` [response](https://developers.home.google.com/cloud-to-cloud/intents/query).

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` | `` `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.QueryResponsePayload` `` Device states for the devices given in the request. |

## QueryResponsePayload

Payload containing device states information.

| Fields ||
|---|---|
| `devices` | ``map<string, `https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.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` | `` `https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Struct` `` States of devices to update. See the **Device STATES** section of the individual trait [reference guides](https://developers.home.google.com/cloud-to-cloud/traits). |
| `notifications` | `` `https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Struct` `` Notifications metadata for devices. See the **Device NOTIFICATIONS** section of the individual trait [reference guides](https://developers.home.google.com/cloud-to-cloud/traits). |

## ReportStateAndNotificationRequest

Request type for the [`ReportStateAndNotification`](https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService.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` > [!WARNING] > This item is deprecated! Deprecated. |
| `payload` | `` `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.StateAndNotificationPayload` `` Required. State of devices to update and notification metadata for devices. |

## ReportStateAndNotificationResponse

Response type for the [`ReportStateAndNotification`](https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService.ReportStateAndNotification) call.

| Fields ||
|---|---|
| `request_id` | `string` Request ID copied from `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.ReportStateAndNotificationRequest`. |

## RequestSyncDevicesRequest

Request type for the [`RequestSyncDevices`](https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService.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`](https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService.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` | `` `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.ReportStateAndNotificationDevice` `` The devices for updating state and sending notifications. |

## SyncRequest

Request type for the [`Sync`](https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService.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`](https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.HomeGraphApiService.Sync) call. This should follow the same format as the Google smart home `action.devices.SYNC` [response](https://developers.home.google.com/cloud-to-cloud/intents/sync).

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` | `` `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.SyncResponsePayload` `` Devices associated with the third-party user. |

## SyncResponsePayload

Payload containing device information.

| Fields ||
|---|---|
| `agent_user_id` | `string` Third-party user ID |
| `devices[]` | `` `https://developers.home.google.com/reference/home-graph/rpc/google.home.graph.v1#google.home.graph.v1.Device` `` Devices associated with the third-party user. |