User storage

In a webhook call, you can store parameter values for a specific user across sessions in user storage. Your Action can then use those stored values later in prompts and conditions, and your webhook code can access values in user storage for a specific user when necessary.

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

Read and write data across conversations

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

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

{
  "responseJson": {
    "session": {
      "id": "1234567890123456789",
      "params": {}
    },
    "prompt": {
      "override": false
    },
    "user": {
      "locale": "en-US",
      "params": {
        "verificationStatus": "VERIFIED",
        "exampleColor": "red"
      }
    }
  }
}
    

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

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

{
  "responseJson": {
    "session": {
      "id": "1234567890123456789",
      "params": {}
    },
    "prompt": {
      "override": false
    },
    "user": {
      "locale": "en-US",
      "params": {
        "verificationStatus": "VERIFIED",
        "exampleColor": "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 user storage:

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

{
  "responseJson": {
    "session": {
      "id": "1234567890123456789",
      "params": {}
    },
    "prompt": {
      "override": false
    },
    "user": {
      "locale": "en-US",
      "params": {
        "verificationStatus": "VERIFIED"
      }
    }
  }
}
    

Reference stored values within prompts

You can reference values stored in user storage in a prompt. To reference the value, use $user.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 user storage as the parameter exampleColor. To access that value in a prompt, you reference that value using $user.params.exampleColor:

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

Reference stored values within conditions

You can also reference values stored in user storage in conditions. To reference the value, use the user.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 user 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 user.params.exampleColor. Your condition expression then looks like this:

user.params.exampleColor == "red"
    

Expiration of user storage data

For verified users, data stored in user storage expires based on their Web & App Activity settings and can also be cleared by the Action itself. For users who aren't verified, Assistant clears the contents of user storage at the end of the conversation.

Actions on Google sets the user's verification status at the start of each conversation based on a variety of indicators when the conversation starts. As one example, a user logged in to Google Assistant on their mobile device has a verification status of VERIFIED.

The following are possible reasons for a user to have a verification status of GUEST:

• The user has personal results turned off.
• The user disabled their Web & App Activity. Keep in mind that some users may have this setting disabled at the domain level.
• If a device has Voice Match enabled, and the match fails or the user invokes the Assistant without using their voice (such as a long press on a Nest Home device).
• The user isn't signed in.

Always check the user's verification status before storing data with user storage to prevent guest users from interacting with a feature that will fail for them.

Visibility to users

As a user, you can view data stored in your user storage for Actions you invoke. You can also remove data stored in your user storage from a specific Action or stop the service from remembering you.

To view your stored data or to stop a service from remembering you, follow these steps:

1. Go to the Assistant directory.
2. Find and select the Action you want to view or clear your user storage for.
3. Scroll to the bottom of the page:
   • To view the contents of your user storage, click [View stored data].
   • To reset data stored in your user storage for the service, click Reset.
   • To remove data stored in your user storage and stop the service from remembering you, click Stop action_name from remembering me.