Session storage

You can store parameter values for a specific user within a conversation in session storage. Your Action can then use those stored values later in prompts and conditions, and your webhook code can access values in session storage for the conversation when necessary.

During a conversation, any data collected using types is stored in session storage. You can also interact with data in session storage using webhook calls. For webhook calls, the state of session storage is passed in an app.handle() request and is stored in the session object.

Data stored in session storage expires when a conversation ends.

Read and write data to session storage

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

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

{
  "responseJson": {
    "session": {
      "id": "12345678901234567890",
      "params": {
        "exampleColor": "red"
      }
    },
    "prompt": {
      "override": false
    }
  }
}
    

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

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

{
  "responseJson": {
    "session": {
      "id": "12345678901234567890",
      "params": {
        "exampleColor": "red"
      }
    },
    "prompt": {
      "override": false
    }
  }
}
    

To clear a previously saved value, set the value to null in a webhook call. The following example clears the value of "exampleColor" in session storage:

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

{
  "responseJson": {
    "session": {
      "id": "12345678901234567890",
      "params": {}
    },
    "prompt": {
      "override": false
    }
  }
}
    

Reference stored values within prompts

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

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

Reference stored values within conditions

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

session.params.exampleColor == "red"