# Home storage

In a webhook call, you can store parameter values across multiple sessions in
the same household (based on [Home Graph](https://developers.google.com/assistant/smarthome/concepts/homegraph)) 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`](https://developers.google.com/assistant/conversational/reference/rest/v1/TopLevel/fulfill#home) object.

> [!WARNING]
> **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](https://developers.google.com/assistant/conversational/storage-user) 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](https://developers.google.com/assistant/conversational/prompts#candidates)
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]
> **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

```javascript
// 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

```javascript
// 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

```javascript
// 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](https://developers.google.com/assistant/conversational/prompts). 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](https://developers.google.com/assistant/conversational/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](https://assistant.google.com/explore):

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]
> **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](https://developers.google.com/assistant/console/simulator),
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]
> **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. |
|---|---|