Bot Session State Snippet

This snippet is for use with actions that have the botSessionState property, 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.

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.

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.

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

1. Configure the botSessionStateVarName (out) property of the Exchange action with the name of the variable to hold the session state identifier. For example, botSessionState.

2. 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.

3. 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()