Bot Session State Snippet

The Bot Session State snippet is required in your script when using actions that have the botSessionState property. This includes actions such as Textbot Exchange and Voicebot Exchange (from here on, both actions are referred to simply as Exchange). The botSessionState property must be configured properly for your virtual agents A software application that handles customer interactions in place of a live human agent. to work as expected. To do this, you must create this snippet in your script and configure the actions correctly as shown in the sections that follow.

The botSessionState property must be configured with the variable that holds the unique identifier for the conversation between the contact and the virtual agent. It is automatically assigned by the virtual agent provider. The identifier prevents a new session from being created with every turn in the conversation and helps the virtual agent maintain context between turns.

The provider creates the identifier when the conversation begins and passes it to the script with the first response. The script stores the identifier in the variable named in the botSessionStateVarName (out) property of the Exchange action. Finally, the script passes the identifier from the previous turn's botSessionStateVarName (out) property to the botSessionState property.

Your scripts should never write to this property or its variable. Your script must be set up correctly to use the bot session state identifier.

This snippet is required unless you use Google Dialogflow CX, where you can set a custom conversation ID in the Custom Payload snippet that serves the same purpose as the Bot Session State snippet. A custom conversation ID is used when transferring contacts from one Dialogflow CX instance to another. If you don't use either ID, a new session ID is generated for each turn in the conversation and your virtual agent will not maintain the context of the conversation. If this happens, no errors are generated, but the system will not function as expected.

Script Setup

When you use an Exchange action, a minimum of two instances of the action are required in your script. The botSessionState property in each of the Exchange actions must be configured differently:

The first instance of the Exchange action is located right after the Begin action at the start of the script. Configure it as follows:
- botSessionState: This must be empty.
- botSessionStateVarName (out): Configure with the name of the variable where you want the script to store the identifier.
The second Exchange action is located later in the script. Configure it as follows:
- botSessionState: Configure with the variable used in botSessionStateVarName (out) in the first instance of the Exchange action. The variable must hold the bot session state identifier in JSON format.
- botSessionStateVarName (out): Configure with the name of the variable where you want the script to store the identifier.
The third and any subsequent instances of the Exchange action are optional. If your script includes these instances, configure them as follows:
- botSessionState: Configure with the variable used in botSessionStateVarName (out) in the previous instance of the Exchange action. The variable must hold the bot session state identifier in JSON format. The bot session state identifier doesn't typically change between turns. However, in case it were to change, the action should be configured to capture the change.
- botSessionStateVarName (out): Configure with the name of the variable where you want the script to store the identifier.

This configuration is required for all virtual agents.

Verify That the botSessionState Property is Set Up Correctly

You can use a script trace to confirm that this property is set up properly.

Run a script trace on an interaction between the virtual agent and a contact. You can use a continuous trace or capture a trace of a specific ANI or DNIS (only for voice interactions).
In the trace window, click the line that corresponds to the first Virtual Agent Hub action (Voicebot Exchange or Textbot Exchange).
In the Variables list, check the botSessionState variable. Its value must be null (empty).
In the trace window, click the next line in the trace after the first Virtual Agent Hub action.
Note the value of the botSessionState variable.
In the trace window, click the line in the trace that corresponds to any subsequent Virtual Agent Hub action.
Check the value of the botSessionState variable. It must be the same as in step 5.

Convert Bot Session State Identifier to JSON

The contents of the variable used in the botSessionStateVarName (out) property must be converted into JSON and passed into the botSessionState property of the second Exchange action in your script. To do this, you can include code in a Snippet action or you can configure the property directly. Both approaches are acceptable. However, the benefit of creating a variable in a Snippet to hold the converted object is that it makes it easier to see where the conversion is happening.

Use a Snippet Action

Configure the botSessionStateVarName (out) property of the Exchange action with the name of the variable to hold the session state identifier. For example, botSessionState.
Add the following line to a Snippet located before the Exchange action in your script:

ASSIGN botSessionStateOut = botSessionStateOut.asJSON()

Use the name of the variable you use in your script.
Configure the botSessionState property in the Exchange action with the name of the variable you used in the ASSIGN statement. For example, botSessionStateOut.

Convert in the Property

If you convert the variable in the botSessionState property, use the botSessionStateVarName (out) variable with the asJSON()function. For example:

botSessionStateVarName (out): botSessionState
botSessionState: botSessionState.asJSON()

Transfer Contacts from One Virtual Agent to Another

To set up the transfer of contacts between virtual agents, you need to set up the bot session state IDs correctly. Each virtual agent must have its own unique bot session state ID. This helps individual virtual agents maintain the context of the conversation that they participate in.

Virtual agent 1: Set up the bot session state variables as described previously on this page.
Virtual agent 2: Set up in the same way, using a different variable in botSessionStateVarName (out) to hold the bot session state ID. Ensure that on the first call to this virtual agent, the botSessionState property is empty. The first turn in the conversation returns a unique bot session state ID to the variable in botSessionStateVarName (out).
All subsequent virtual agents: Set up the same as for virtual agent 2, using a unique variable for the bot session state ID.

This method works for all supported virtual agent providers unless you are transferring between two Google Dialogflow CX virtual agents. In this case, a different method is required.