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 Client Library for node.js, you can interface with the conversation token as a JSON object using Conversation.data.

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 Conversation.user.storage.

Save data between turns of a conversation

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

JSON
{
    "conversationToken": "count=1",
    "expectUserResponse": true,
    "expectedInputs": [
        {
            "inputPrompt": {
                "richInitialPrompt": {
                    "items": [
                        {
                            "simpleResponse": {
                                "textToSpeech": "Howdy! I can tell you fun facts about almost any number, like 42. What do you have in mind?",
                                "displayText": "Howdy! I can tell you fun facts about almost any number. What do you have in mind?"
                            }
                        }
                    ],
                    "suggestions": []
                }
            },
            "possibleIntents": [
                {
                    "intent": "actions.intent.TEXT"
                }
            ]
        }
    ]
}
Node.js
function simpleResponse(conv) {
  conv.data.count = 1;
  conv.ask(new SimpleResponse({
    speech: 'Howdy! I can tell you fun facts about ' +
        'almost any number, like 42. What do you have in mind?',
    text: 'Howdy! I can tell you fun facts about almost any ' +
        'number. What do you have in mind?',
  }));
}

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

Save data across conversations

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.

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

JSON
{
    "userStorage": "count=1",
    "expectUserResponse": true,
    "expectedInputs": [
        {
            "inputPrompt": {
                "richInitialPrompt": {
                    "items": [
                        {
                            "simpleResponse": {
                                "textToSpeech": "Howdy! I can tell you fun facts about almost any number, like 42. What do you have in mind?",
                                "displayText": "Howdy! I can tell you fun facts about almost any number. What do you have in mind?"
                            }
                        }
                    ],
                    "suggestions": []
                }
            },
            "possibleIntents": [
                {
                    "intent": "actions.intent.TEXT"
                }
            ]
        }
    ]
}
Node.js
function simpleResponse(conv) {
  conv.user.storage.count = 1;
  conv.ask(new SimpleResponse({
    speech: 'Howdy! I can tell you fun facts about ' +
        'almost any number, like 42. What do you have in mind?',
    text: 'Howdy! I can tell you fun facts about almost any ' +
        'number. What do you have in mind?',
  }));
}
    

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

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 Conversation.user.storage to {} (empty object).

JSON
{
    "resetUserStorage": true,
    "expectUserResponse": true,
    "expectedInputs": [
        {
            "inputPrompt": {
                "richInitialPrompt": {
                    "items": [
                        {
                            "simpleResponse": {
                                "textToSpeech": "Howdy! I can tell you fun facts about almost any number, like 42. What do you have in mind?",
                                "displayText": "Howdy! I can tell you fun facts about almost any number. What do you have in mind?"
                            }
                        }
                    ],
                    "suggestions": []
                }
            },
            "possibleIntents": [
                {
                    "intent": "actions.intent.TEXT"
                }
            ]
        }
    ]
}
Node.js
function simpleResponse(conv) {
  conv.user.storage = {};
  conv.ask(new SimpleResponse({
    speech: 'Howdy! I can tell you fun facts about ' +
        'almost any number, like 42. What do you have in mind?',
    text: 'Howdy! I can tell you fun facts about almost any ' +
        'number. What do you have in mind?',
  }));
}
    

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.