Try the new Conversation API Playground to learn more about using our API!

Save Data in Conversation

If your Action needs to save state between turns of a conversation or across different conversations, you can use the conversationToken or the userStorage fields of your AppResponse object.

The conversationToken field is a string that contains an opaque token that is recirculated to the Actions every conversation turn. For example, if you set the value to "count=1" in your AppResponse for the first turn of the conversation, the AppRequest received by your Action for the second turn of the conversation contains "count=1" in its conversationToken. The token is always initialized to an empty string at the beginning of a conversation. If you are using the Actions on Google Node.js client library, you can interface with the conversation token as a JSON object using conv.data, where conv is your instance of Conversation.

The userStorage field is a string that contains an opaque token supplied by the Action that is saved across conversations for a particular user. For example, a game can save the highest score of a user in userStorage, and use its value in the welcome message every time the user starts a new conversation. If you are using the Actions On Google Client Library for node.js, you can interface with the user storage as a JSON object using conv.user.storage, where conv is your instance of Conversation.

Save data between turns of a conversation

The following sample shows how to save a counter in the conversation token of your AppResponse:

Node.js
function simpleResponse(conv) {
  conv.data.count = 1;
  conv.ask('Hi there, what can I help you with today?');
}
Dialogflow JSON
{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Hi there, what can I help you with today?"
            }
          }
        ]
      },
      "userStorage": "{\"data\":{}}"
    }
  },
  "outputContexts": [
    {
      "name": "/contexts/_actions_on_google",
      "lifespanCount": 99,
      "parameters": {
        "data": "{\"count\":1}"
      }
    }
  ]
}
Actions SDK JSON
{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "Hi there, what can I help you with today?"
              }
            }
          ]
        }
      },
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ]
    }
  ],
  "conversationToken": "{\"data\":{\"count\":1}}",
  "userStorage": "{\"data\":{}}"
}

See our "Provide helpful reprompts and fail gracefully" best practice guide for a practical usage example.

Save data across conversations

The following sample shows how to save a counter in the user storage of your AppResponse:

Node.js
function simpleResponse(conv) {
  conv.user.storage.count = 1;
  conv.ask('When is your birthday?');
}
Dialogflow JSON
{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "When is your birthday?"
            }
          }
        ]
      },
      "userStorage": "{\"data\":{\"count\":1}}"
    }
  },
  "outputContexts": [
    {
      "name": "/contexts/_actions_on_google",
      "lifespanCount": 99,
      "parameters": {
        "data": "{}"
      }
    }
  ]
}
Actions SDK JSON
{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "When is your birthday?"
              }
            }
          ]
        }
      },
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ]
    }
  ],
  "conversationToken": "{\"data\":{}}",
  "userStorage": "{\"data\":{\"count\":1}}"
}

See our "Personalize the conversation with user preferences" best practice guide for a practical usage example.

Legal note: Obtaining consent prior to accessing userStorage. Some countries have regulations that require developers to obtain consent from the user before they can access, or save certain information (e.g. personal information) in the userStorage. If you operate in one of these countries and you want to access, or save such information in userStorage, you must use the Confirmation helper to ask consent to the user and obtain the consent before you can start storing such information in userStorage.

User storage expiration

When the Assistant can match an identity to the user, the contents of user storage never expires, and only the user or the Action itself can clear it.

When the Assistant can't match an identity to the user, the content of user storage is cleared at the end of the conversation. Examples of cases where the Assistant can't match an identity to the user are:

  • voice match is set up and there is no match.
  • The user disabled personal data.

Clear content of the userStorage field

You can clear the content of the userStorage field of your Action by setting the resetUserStorage field of your AppResponse to true. If you set the value of userStorage to an empty string, the value of userStorage remains unaltered in the next turn of conversation. This allows you to avoid sending back the whole userStorage in turns where its content didn't change.

If you are using the Actions On Google Client Library for node.js, you can just set the value of conv.user.storage to {} (empty object).

Node.js
function simpleResponse(conv) {
  conv.user.storage = {};
  conv.ask('Okay, I cleared your data');
}
Dialogflow JSON
{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Okay, I cleared your data"
            }
          }
        ]
      },
      "userStorage": "{\"data\":{}}"
    }
  },
  "outputContexts": [
    {
      "name": "/contexts/_actions_on_google",
      "lifespanCount": 99,
      "parameters": {
        "data": "{}"
      }
    }
  ]
}
Actions SDK JSON
{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "Okay, I cleared your data"
              }
            }
          ]
        }
      },
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ]
    }
  ],
  "conversationToken": "{\"data\":{}}",
  "userStorage": "{\"data\":{}}"
}

As a user, you can view the content of the user storage field in an Action you invoked. You can also remove your stored user data from that specific Action by stopping the service from remembering you.

  1. Open the Assistant app on your phone.
  2. Click on the drawer icon.

  3. In the Explore tab, find the Action you want to view or clear the user storage for and tap on it to open the details page.
  4. Scroll down to the bottom of the page.
    • To view the content of the user storage field, tap [View stored data].
    • To remove the stored user data, tap Stop $action from remembering me.