Textbot Exchange

This help page is for Desktop Studio. This information is also available for CXone Studio.

The icon for the Textbot Exchange action.

Integrates a self-service virtual agent A software application that handles customer interactions in place of a live human agent. with chat scripts. This action is used in a loop in the script. A script must contain at least two TextBot Exchange actions. Your virtual agent must support this action.

The TextBot Exchange action is for complex virtual agents or for when you need to customize the virtual agent's behavior from turn to turn. It monitors the conversation between the contact and the virtual agent A software application that handles customer interactions in place of a live human agent. turn by turn. It sends each utterance What a contact says or types. to the virtual agent. The virtual agent analyzes the utterance for intent The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish and context and determines which response to give. TextBot Exchange passes the response to the contact. When the conversation is complete, the action continues the script.

Double-clicking this action opens Virtual Agent Hub, where you can manage all of your virtual agent bots.

Supported Script Types


Email	Chat	SMS	Digital

Comparison of Similar Actions

The following actions have similar functions, but with some key differences:

Textbot Exchange: This action is used for complex virtual agent interactions. It allows you to include exchange parameters and to customize various aspects of the conversation between contact and virtual agent.
Voicebot Exchange: This action is used for complex virtual agent interactions. It allows you to include exchange parameters and to customize various aspects of the conversation between contact and virtual agent.

Supported Virtual Agents

This action supports the following virtual agents:

Before you can assign a virtual agent to this action, you must add and configure an app for the virtual agent in Virtual Agent Hub. You only need one app for each virtual agent you use. You can assign the same app to multiple virtual agent actions in your scripts. Refer to the help page for the virtual agent provider you're using for configuration details.

Input Properties

These properties define data that the action uses when executing.

One or more of this action's properties require a Snippet action with custom code.

Property	Details
Caption	Enter a short phrase that uniquely identifies this action in the script. The caption appears on the script canvas under the action icon. The default is the action name.
virtualAgentID	The name of the virtual agent selected in the Virtual Agent Hub. When you assign a virtual agent app to a Studio action in Virtual Agent Hub, it automatically populates this property. The name is the name used in the Virtual Agent (Bot) Name field in the Virtual Agent Hub app.
automatedIntent	Enter a specific intent by name for the virtual agent to respond to, rather than having the virtual agent interpret collected user input. A common use case for this is to elicit the initial Welcome message from the virtual agent. Welcome is the standard string for initial greetings.
userInput	The message that the contact writes in the chat window and is passed to the virtual agent as text input.
customPayload	Configure this property only if you need to pass custom payload data to the virtual agent. The custom payload object is populated from the Studio script. You can use it to pass information such as the contact's name from a CRM Third-party systems that manage such things as contacts, sales information, support details, and case histories. to be used in a Welcome message. Enter the name of the JSON object that passes data from the script to the virtual agent. You must define the custom payload object in a Snippet action. The object must be converted to JSON, either in the snippet or in the customPayload property. Requirements for specific virtual agent providers: Amazon Lex V1: This property is required even if you don't need to pass data to the virtual agent. Add a snippet with a placeholder value. Google Dialogflow ES: This property is used to pass the context for an intent The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish. Review the best practices for custom payload with Google Dialogflow ES to ensure you handle it appropriately. Google Dialogflow CX: Review the best practices for custom payload with Google Dialogflow CX to ensure you handle it appropriately. Don't use this property if you need to process data that the virtual agent returns to the script. Instead, use the customPayloadVarName (out) variable.
botSessionState	Configure 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 this 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.

Output Properties

These properties contain variables that hold data returned from executing the action. They're available for reference and use when the action completes.

Property	Description
nextPromptVarName (out)	Defines the behaviors for prompting the user on the next conversational turn.
customPayloadVarName (out)	Returns custom JSON data from the virtual agent to the script. Use this variable when you want the script to process data that the virtual agent provides. May contain fulfillment data. If you want to provide data to the virtual agent, use the customPayload property.
errorDetailsVarName (out)	Prompts the error intent sequence; can lead to a transfer to a live agent.
intentInfoVarName (out)	A variable that holds details from the virtual agent indicating current user intent.
botSessionStateVarName (out)	Holds the variable where the script stores the bot session state identifier sent by the virtual agent provider. The contents of the variable is passed to the botSessionState property. This property must be configured properly for your virtual agent to function properly. More information about how to configure it is available on the Bot Session State Snippet help page.

Result Branch Conditions

Result branch conditions allow you to create branches in your script to handle different outcomes when an action executes.

Condition	Description
Default	Path taken unless the script meets a condition that requires it to take one of the other branches. It is also taken if the action's other branches are not defined.
OnPromptAndCollectNextResponse	Path taken if the virtual agent has determined that the interaction should continue and is ready for more human input from the contact. Prompts for the next turn in the conversation.
OnError	Path taken when there is an unexpected problem (for example, poor connectivity, syntax errors, and so forth). The _ERR variable should be populated with a condensed explanation of the problem.
OnReturnControlToScript	Path taken if the virtual agent indicated that the conversation finished and gives control back to the Studio script to transfer or end the call. There may be fulfillment data to be processed in the customPayload result.

Snippet Action Code

One or more of this action's properties require a Snippet action with the following custom code:

Best Practices for Custom Payload with Google Dialogflow CX

When using this action with Google Dialogflow CX follow these best practices for integrating custom payloads:

Dialogflow CX doesn't use contexts to pass data to Dialogflow intents The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish like Dialogflow ES does.
You can pass custom data to Dialogflow CX using JSON key-value pairs. In a Snippet action action in your script, create a dynamic customPayload object and add the key-value pairs to it. For example:
```
DYNAMIC customPayload
customPayload.ani = ani
customPayload.contactID = contactId
customPayload.masterContactId = masterId
customPayloadJSON = "{customPayload.asJSON()}"	
```
In the Exchange or Conversation action in your script, configure the customPayload property with variable that has the asJSON() function in its value. You can find this variable in the customPayload object.
Pass the customPayload JSON to the virtual agent using the Payload property of QueryParameters. See Google documentation on QueryParameters for Google Dialogflow CX.
Data passed through QueryParameters is received by a webhook in Dialogflow CX. You can write code in the Dialogflow CX console to handle the passed data.
Do not nest an object within the customPayload object. Nested objects are sent as literal strings.
To pass custom data from your Dialogflow CX virtual agent back to the script, use the Custom Payload field in the Dialogflow CX console. Make sure you're in the console for the virtual agent you're using with CXone. Map this to your script using the customPayloadVarName (out) variable in the voice or chat Studio action in your script. For example, you can use this to set the next prompt's behaviors.
Parameters set using customPayload can only be used in the external webhook. If you want to set parameters for use outside the external webhook, set them in a Snippet action with the session_params field. For example:
```
{
	"session_params":
	{ 
		"name": "Winnie Le Pooh"
		"job": "Food critic"
		"location": "Hundred Acre Wood"
	}
}
```
Access the session parameters in the Dialogflow CX agent intent using the following syntax:

$session.params.name = Winnie Le Pooh

$session.params.job = Food critic

$session.params.location = 100 Acre Wood

Session parameters are only used with Dialogflow CX virtual agents. To achieve a similar result with Dialogflow ES, use contexts.
Speech context hints can be passed with custom payload in the speechContexts parameter. The value of speechContexts.phrases must be a Google class token for the hint you want to give. The token must match the language and locale of your contacts. For example:
```
DYNAMIC customPayload
customPayload.speechContexts.phrases="$OOV_CLASS_ALPHANUMERIC_SEQUENCE"
customPayload.speechContexts.boost=10		
```

Best Practices for Custom Payload with Google Dialogflow ES

When using this action with Google Dialogflow ES, follow these best practices for integrating custom payloads:

CustomPayload is used to pass context for an intent The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish. Context helps the virtual agent understand the user's intent. Contexts aren't required, but they help the virtual agent match an utterance What a contact says or types. to an intent.
In a Snippet action in your script, create a customPayload object that follows the format outlined in the Google Dialogflow ES documentation for REST Resource: projects.agent.sessions.context. The Studio online help provides additional information about dynamic data objects.
You can also pass custom data with customPayload without contexts. To do this, include standard JSON key-value pairs in a dynamic data object.
Speech contexts are passed in custom payload in the speech_contact parameter. You can see the contents of this parameter in Studio traces and application logs.
The customPayload dynamic object is passed as a virtual agent parameter as JSON, as shown in the example script.
Speech context hints can be passed with custom payload in the speechContexts parameter. The value of speechContexts.phrases must be a Google class token for the hint you want to give. The token must match the language and locale of your contacts. For example:
```
DYNAMIC customPayload
customPayload.speechContexts.phrases="$OOV_CLASS_ALPHANUMERIC_SEQUENCE"
customPayload.speechContexts.boost=10		
```