Method: devices.reportStateAndNotification

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. See Implement Report State for more information. This method updates a predefined set of states for a device, which all devices have according to their prescribed traits (for example, a light will have the OnOff trait that reports the state on as a boolean value). 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.

The third-party user's identity is passed in as agentUserId. The agent is identified by the JWT signed by the partner's service account.

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

Token to maintain state in the follow up notification response.

payload

object(StateAndNotificationPayload)

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.

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.

notifications

object (Struct format)

Notifications metadata for devices.