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.

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.

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:

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

{
  "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:

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

{
  "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:

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

{
  "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:

{
  "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:

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.

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:

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

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