Context Store
The Context Store within ServisBOT is a key-value & object store, used for building up known information about a user within a conversation. Context is specific to an individual bot user, and is shared across conversations. A number of variables about a conversation are also available within the context store, for use in your conversation.
Ways to Set & Collect Context about your users
- Upon messenger initialization, context known at that point about a user can be set
- During the course of a conversation, [context can be updated])/getting-started/installation/configuration/#updating-the-context) using client-side javascript from the web page the bot is embedded upon
- During the course of the conversation, context can be set via a botnet action as part of intent fulfillment.
- During the course of authenticating a user using Secure Session, context can be set as part of the result of a lookup / response from an IDP
- Within action flow (or classic flow), context can be set - reflecting a user’s choice, preference, or the data received in response to an API call.
Types of data which can be stored
The context store is a JSON object store - meaning flat strings, booleans and numbers can be stored - but also complex, deep nested objects.
The maximum size this context store can grow to is 10kb. That’s room for a lot of data, but we would discourage the storing of things like large API response paylaods.
Conversation variables
Here are a number of useful conversational variables you can use within conversation. The table shows how to reference the variable from within a Flow, and also within Fulfilment Actions on an NLP based Intent.
| Variable Name | In Flow | In NLP Workers | Note | |
|---|---|---|---|---|
| What the user said | msg.payload.user.message |
state.input.utteranceText |
Note in flow msg.payload.state.input.utteranceText only reflects what the user said last in order to trigger an intent - msg.payload.user.message always reflects what the user last said. |
|
| Custom Variables | msg.payload.context.variableName |
variableName |
(where variableName is the key to the custom context variable) |
|
| Custom entities detected in utterance | msg.payload.context.state.entities |
state.entities |
||
| Intent history | msg.payload.context.state.history |
state.history |
Previous intents a user has visited | |
| Browser language | msg.payload.context.state.input.language |
state.input.language |
Browser detected language - not as a result of language detection pipeline | |
| Whether the user is from a Mobile Device | msg.payload.context.state.input.isMobile |
state.input.isMobile |
||
| Whether the user is in a Virtual Assistant | msg.payload.context.state.isVa |
state.isVa |
A boolean value - BUT, may be undefined (treated as false) |
|
| Named Entities detected in the user’s message | msg.payload.context.state.va.entities |
state.va.entities |
When used in conjunction with Named Entitiy Recognition ingress pipeline & Virual Assistant (or Enhanced Bot) | |
| Status code of API Connector | msg.apiConnector.myApi.status |
N/A | Where the API Connector node is named myApi. If node is not named, defaults to alias of BaaS API connector. |
|
| Response of API Connector | msg.apiConnector.myApi.response |
N/A | Where the API Connector node is named myApi. If node is not named, defaults to alias of BaaS API connector. Any JSON will be parsed and available as an object. |
To use a variable in an NLP worker:
When referencing a variable from within the fulfillment section of an intent, we use a syntax called VTL to lookup our variables. From the table below, What the user said is located at state.input.utteranceText.
In VTL, variables are referenced by wrapping the value in curly braces: ${variableName}
To use a variable in a Flow Node:
Taking our first exmaple, to echo what the user just said back to the user:
Within a node of a flow (in this case, a “dialogue”), you can always lookup variables using the variable source dropdown, by selecting the msg. option.
Then, we enter the variable name for What the user said from our table below. We always omit the msg. portion, since this is already provided in the dropdown.
Context Available in Flow Nodes:
The available variable namespace when rendering a timeline element in Classic Flow differs depending on the node you’ve selected. To use a variable listed above, you’ll need to set it in the relevant namespace, easily done using the change node.
In all cases, nodes use VTL syntax (${variableName}) to reference values.
| Node Name | Purpose | Context Available when rendering | User’s input/choice available at: |
|---|---|---|---|
| Interaction | Collect a user’s choice from a markup timeline element | msg.* |
msg.payload.user.message |
| Markup | Display a static piece of markup, then move on in the conversation. | msg.payload.user.* |
N/A (markup is typically used for static content.) |
| Dialogue | Shortcut to sending a simple TxtMessage | msg.payload.user.* |
N/A |
| CMS | Take stored CMS content and output it to the conversation | msg.payload.user* |
N/A |
| Menu | Renders a simple menu of choices | No variables available | msg.payload.menuInteraction |
| secureInput | Collect a secret value from a user securely | No variables available | SRN of the secret input, which can be referenced in a BaaS at: msg.payload.user.secureInputSrn |
Example:
To output the browser language in a markup node, we use the Change node to set it to the namespace for Markup (msg.payload.user.*):
Then, we can reference language in the markup node directly.
Note however, if we were using the Interaction node (to reflect a user’s choice), we could lookup the $language property directly, since it has the entire payload available to it using ${payload.context.state.input.language}.