Intents

Smart home intents are simple messaging objects that describe what Cloud-to-cloud integration to perform such as turn on a light or cast audio to a speaker.

All of the smart home intents are contained in the action.devices namespace and you must provide fulfillment for them. Whenever Google Assistant sends an intent to fulfillment, a user's third-party OAuth 2 access token is passed in the Authorization header.

These are the supported smart home intents:

SYNC

The action.devices.SYNC intent is used to request the list of smart home devices that the user has connected and are available for use.

When a user sets up their devices with the Google Home app (GHA), they also get authenticated to your cloud infrastructure. Then, Assistant receives an OAuth2 token. At this point, Assistant sends a action.devices.SYNC intent to your fulfillment to retrieve the initial list of user devices and capabilities from your cloud infrastructure.

This figure shows the interaction between the Google infrastructure and the partner infrastructure. From the Google infrastructure there is a list of partners that is available to the Assistant client app, which then flows to the partner infrastructure to complete OAuth authentication. The OAuth authentication on the partner side is the partner setup webview, OAuth webview, optional settings ands terms, and partner cloud services. The partner infrastructure, then returns the OAuth credentials to the Assistant client app. The partner cloud services sends available devices and capabilities to Assistant services, which then stores the information in the Home Graph.
Figure 1: Interaction between Google and Partner infrastructure

To avoid unlinking and relinking a user's account, you can send a request sync to Assistant. This sends the action.devices.SYNC intent to your fulfillment to sync the list of devices and capabilities. See Implement Request Sync for more information.

Flow diagram of a SYNC intent
Figure 2: SYNC intent

During local fulfillment setup, the Local Home platform checks the SYNC response from your smart home Action's cloud fulfillment. To learn more about how to modify your SYNC response to support local fulfillment, see Update SYNC response in cloud fulfillment.

QUERY

The action.devices.QUERY intent is used to query the current state of smart home devices.

When users are querying device status, to answer a question such as Hey Google, what lights are on in the kitchen?, Assistant sends a action.devices.QUERY intent to your fulfillment.

Flow diagram of a QUERY intent
Figure 3: QUERY intent

For the best user experience, you should implement Report State to proactively report the current state of a user's devices directly to Google Home Graph. For example, this lets Assistant know if your user turned on a smart light with a physical light switch.

Reporting device state using Report State
Figure 4: Report device state

EXECUTE

The action.devices.EXECUTE intent is used to provide commands to execute on smart home devices.

When users send commands to devices with Assistant, your fulfillment receives a action.devices.EXECUTE intent to your fulfilment that describes the action and the devices to act upon. A user can execute an action on a device with a command such as Hey Google, turn on my living room lights.

Flow diagram of an EXECUTE intent
Figure 5: EXECUTE intent

DISCONNECT

The action.devices.DISCONNECT intent is triggered to inform you when a user has unlinked the app account from Assistant. After receiving a action.devices.DISCONNECT intent, you should not report state for this user's devices.

Previous
Device types and traits
Next
Fulfillment