Home storage

In a webhook call, you can store parameter values across multiple sessions in the same household (based on Home Graph) in home storage. Your Action can then use those stored values later in prompts and conditions, and your webhook code can access values in home storage for a specific household when necessary.

The state of home storage is passed in an app.handle() request and is stored in the home object.

Important: Do not use home storage to store any personal data. Home storage data applies across multiple individuals in the same household who use the same Action. For user-specific data, instead use user storage and ask for the user's consent before saving any personal data.

Limitations

Home storage can't be used with mobile devices, as they aren't part of a Home Graph. In your webhook code, use the HOME_STORAGE device capability to branch business logic based on what the user's device is capable of.

You must opt in to use home storage:

1. In the Actions console, go to Deploy > Directory information.
2. In the Additional Information section, check the box for Home storage.

Note: When using home storage, Google additionally presents a disclaimer once to verified users, and on each invocation to guest users (up to once per 10 minutes).

Read and write data in a household

To update or set a new value in home storage, assign the value to the params field of the home object in a webhook call. The following example sets "exampleColor" to "red" in home storage:

Node.js

// Assign color to home storage
app.handle('storeColor', conv => {
  let color = 'red';
  conv.home.params.exampleColor = color;
});
    

JSON

{
  "responseJson": {
    "session": {
      "id": "1234567890123456789",
      "params": {}
    },
    "prompt": {
      "override": false
    },
    "home": {
      "params": {
        "exampleColor": "red"
      }
    }
  }
}
    

To access data stored in home storage, assign it to a variable in a webhook call. The following example retrieves a value from "exampleColor" in home storage:

Node.js

// Retrieve color from home storage
app.handle('getStoredColor', conv => {
  let color = conv.home.params.exampleColor;
});
    

JSON

{
  "responseJson": {
    "session": {
      "id": "1234567890123456789",
      "params": {}
    },
    "prompt": {
      "override": false
    },
    "home": {
      "params": {
        "homeColor": "red"
      }
    }
  }
}
    

To clear a previously saved value, set the value to null in a webhook call. The following example clears the value of "exampleColor" in home storage:

Node.js

// Clear color from home storage
app.handle('clearStoredColor', conv => {
  conv.home.params.exampleColor = null;
});
    

JSON

{
  "responseJson": {
    "session": {
      "id": "1234567890123456789",
      "params": {}
    },
    "prompt": {
      "override": false
    },
    "home": {
      "params": {}
    }
  }
}
    

Reference stored values within prompts

You can reference values stored in home storage in a prompt. To reference the value, use $home.params.PARAMETER_NAME syntax, where PARAMETER_NAME is the name given in the webhook when the parameter was set.

For example, you previously stored a color value in home storage as the parameter exampleColor. To access that value in a prompt, you reference that value using $home.params.exampleColor:

JSON

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Your favorite color is $home.params.exampleColor."
      }]
    }
  }]
}
    

Reference stored values within conditions

You can also reference values stored in home storage in conditions. To reference the value, use the home.params.PARAMETER_NAME syntax, where PARAMETER_NAME is the name given in the webhook when the parameter was set.

For example, you previously stored a color value in home storage as the parameter exampleColor, and you want to match it with the value "red" in a condition. In your condition, you reference the stored value using home.params.exampleColor. Your condition expression then looks like this:

Condition syntax

home.params.exampleColor == "red"
    

Expiration of home storage data

Home storage data is wiped after 90 consecutive days of the Action not being invoked. Invoking the Action on any device associated with the Home Graph structure resets the 90 day timer. If a Home Graph structure is deleted, the corresponding home storage data is cleared.

For Actions that use home storage, Home Graph structure managers can clear home storage for structures they manage from the Action's page in the Assistant directory:

1. Find and select the Action you want to view or clear your user storage for.
2. Scroll to the bottom of the page:
   • To remove data stored for you in home storage, click Stop action_name from remembering me.

Note: Clearing home storage clears the stored values for guests and other Home Graph structure managers.

When the manager of a device dissociates it from the structure, home storage is also dissociated. Home storage data continues to be associated with a device even if the structure manager changes, unless a structure manager clears it.

Home storage data in the simulator

When testing your Action using the simulator in the Actions console, data stored in home storage behaves slightly differently from on a physical device. The simulator is considered part of its own Home Graph, so data does not persist to other devices you might have in your network. Additionally, home storage data does not persist across sessions when the Simulate unverified user simulator setting is enabled.

Sample interaction

Here's a sample interaction of a signed-in user on their first invocation of the Action:

User query	Hey Google, talk to ExampleAction.
Assistant response	Getting ExampleAction.
Assistant response	Just so you know, ExampleAction gets saved every time you play it, so others in your household can pick up where you left off.
ExampleAction response	Hello verified user. You are on level 0. Say next, reset, or cancel.
User query	Next.
ExampleAction response	You are on level 1.
User query	Leave.

Then, when the same verified user returns to the Action after some time:

User query	Hey Google, talk to ExampleAction.
Assistant response	Getting ExampleAction.
ExampleAction response	Hello verified user. You are on level 1. Say next, reset, or cancel.
User query	Next.
ExampleAction response	You are on level 2.
User query	Leave.

The next day, an unverified user interacts with the Action on another device within the same household (as specified on Home Graph).

Note: Google presents the disclaimer only if it has been at least 10 minutes since the last invocation of the Action in that household.

User query	Hey Google, talk to ExampleAction.
Assistant response	Getting ExampleAction.
Assistant response	Just so you know, ExampleAction gets saved every time you play it, so others in your household can pick up where you left off.
ExampleAction response	Hello guest user. You are on level 2. Say next, reset, or cancel.
User query	Next.
ExampleAction response	You are on level 3.
User query	Leave.