We want to hear your thoughts on the Google Smart Home platform. Join a user study and receive a gift for your input. Click here to sign up.

Method: devices.reportStateAndNotification

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 agentUserId (see ReportStateAndNotificationRequest). This request must be authorized using service account credentials from your Actions console project.

HTTP request

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation
{
  "requestId": string,
  "eventId": string,
  "agentUserId": string,
  "followUpToken": string,
  "payload": {
    object (StateAndNotificationPayload)
  }
}
Fields
requestId

string

Request ID used for debugging.

eventId

string

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

agentUserId

string

Required. Third-party user ID.

followUpToken

string

Deprecated. Token to maintain state in the follow up notification response.

payload

object (StateAndNotificationPayload)

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

Response body

If successful, the response body contains data with the following structure:

Response type for the devices.reportStateAndNotification call.

JSON representation
{
  "requestId": string
}
Fields
requestId

string

Request ID copied from ReportStateAndNotificationRequest.

Authorization Scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.

StateAndNotificationPayload

Payload containing the state and notification information for devices.

JSON representation
{
  "devices": {
    object (ReportStateAndNotificationDevice)
  }
}
Fields
devices

object (ReportStateAndNotificationDevice)

The devices for updating state and sending notifications.

ReportStateAndNotificationDevice

The states and notifications specific to a device.

JSON representation
{
  "states": {
    object
  },
  "notifications": {
    object
  }
}
Fields
states

object (Struct format)

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

notifications

object (Struct format)

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