Textbot Exchange

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.

This action is for complex bots or for when you need to customize the bot's behavior from turn to turn.

TextBot Exchange monitors the conversation between the contact and the bot Virtual agent designed to handle specific interactions turn by turn. It sends each utterance What a contact says or types. to the bot. The bot analyzes the utterance for intent What the contact wants to communicate or accomplish and context and determines which response to give. TextBot Exchange returns the bot's response to the contact. When the conversation is complete, the action continues the script.

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

Supported Script Types


Email	Chat	SMS

Related Studio Actions

The Textbot Conversation action is similar to this action but is only suitable for very simple bots. It doesn't allow for customization of the bot's behavior from turn to turn.

Voicebot Conversation and Voicebot Exchange are also similar, providing the same functions as Textbot Conversation and Textbot Exchange, but for voice-based interactions.

Supported Virtual Agents

This action supports the following virtual agents:

Before you can assign a virtual agent bot to this action, you must add and configure the bot in the CXone Virtual Agent Hub. You only need to add a virtual agent to the Virtual Agent Hub once, then you can assign it to actions as needed. Refer to the topic for the virtual agent you're using for configuration details.

Properties

Some properties require a Snippet action. The Snippet Action Code section on this page has information about the required code. For information about other Snippet code that may be useful, see the Snippet action topic.

Property	Details
virtualAgentID	Corresponds to the name of the virtual agent selected in the CXone Virtual Agent Hub. See the Supported Virtual Agents section on this page for more information.
automatedIntent	Enter a specific intent by name for the bot to respond to, rather than having the bot interpret collected user input. A common use case for this is to elicit the initial Welcome message from the bot. Welcome is the standard string for initial greetings.
userInput	The message that the contact writes in the chat window and is passed to the bot as text input.
customPayload	A generic JSON object that passes data from the script to the bot. It's populated from the Studio script. You can use it to pass information such as the contact's name from the CRM to be used in the Welcome message. You can convert this object using the asjson() method in a Snippet action. For Amazon Lex bots, this property is required. Use a Snippet action with code from the customPayload snippet. Other bots may benefit from this property and the customPayload snippet. For Google Dialogflow ES bots, this property is used to pass the context for an intent What the contact wants to communicate or accomplish. For more information about using this property with Google Dialogflow ES, see the Best Practices for Custom Payload with Google Dialogflow ES section in this topic. For Google Dialogflow CX bots, see the Best Practices for Custom Payload with Google Dialogflow CX section. Don't use this property if you need to process data that the bot returns to the script. Instead, use the customPayloadVarName (out) variable.
botSessionState	A unique identifier assigned to a conversation with a bot. This identifier is created when the conversation begins and is passed back as a bot parameter to maintain a session for the current conversation.

Branches

Branch	Details
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 other branches are not defined.
OnPromptAndCollectNextResponse	Path taken if the bot has determined that the interaction should continue and is ready for more human input. 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 bot 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.

Output Variables

Variable	Details
nextPromptVarName (out)	Defines the behaviors for prompting the user on the next conversational turn.
customPayloadVarName (out)	Returns custom JSON data from the virtual agent bot to the script. Use this variable when you want the script to process data that the bot provides. May contain fulfillment data. If you want to provide data to the bot, use the customPayload property.
errorDetailsVarName (out)	Prompts the error intent sequence; can lead to a transfer to a live agent.
intentInfoVarName (out)	Lists details from the bot indicating current user intent.

Snippet Action Code

Some of this action's properties require Snippet action code. You can follow these examples when creating your script.

customPayload

View customPayload snippet code example

Use this code with actions that have the customPayload property to pass data from the script to the virtual agent bot Virtual agent designed to handle specific interactions. When you configure the customPayload property, use the asJSON() method. For example, {customPayload.asJSON()}.

This snippet is required for Amazon Lex bots, even if you don't need to pass information to the bot. Amazon Lex uses the data passed through the customPayload property to set SessionAttributes for your Lex bot. Other bots may also benefit from the snippet code that passes a placeholder.

This snippet is required for Google Dialogflow ES bots. It passes context information that the bot uses to determine intent What the contact wants to communicate or accomplish. Follow the recommended best practices for integrating custom payload data with Google Dialogflow ES.

If you don't need to pass information to the bot, follow this example:

copy

Example code with placeholder

DYNAMIC customPayload
customPayload.placeholder=""

Download this snippet.

If you want to pass information to the bot, follow this example:

copy

Example of passing data

DYNAMIC customPayload
customPayload.context.id="information"
customPayload.context.lifespan=1
customPayload.context.parameters.name="Fenrir"
customPayload.context.parameters.age="19"
customPayload.context.parameters.date="20201020"

Download this snippet.

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 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 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 the variable you used in the customPayload object with the asJSON() method.
Pass the customPayload JSON to the bot 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.
To pass custom data from your Dialogflow CX bot back to the script, use the Custom Payload field in the Dialogflow CX console for the virtual agent you're using with CXone. Map this to your script using the customPayloadVarName (out) variable in the voicebot or chatbot Studio action in your script. For example, you can use this to set the next prompt's behaviors.

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 What the contact wants to communicate or accomplish. Context helps the bot understand the user's intent. Contexts aren't required, but they help the bot match an utterance What a contact says or types. to an intent.
In a Snippet action in your script, create a DYNAMIC customPayload object that follows the format outlined in the Google Dialogflow ES documentationGoogle Dialogflow CXdocumentation for REST Resource: projects.agent.sessions.context. The Studio online help provides additional information about dynamic data variables and objects.
You can also pass custom data with customPayload without contexts. To do this, include standard JSON key-value pairs to a DYNAMIC object.
The customPayload dynamic object is passed as a bot parameter as JSON, as shown in the example script.

Example Script Using TextBot Exchange

An example Studio script showing how the Textbot Exchange action might be used.

Download this script.

Example Script for CustomPayload with Google Dialogflow ES

This script is an example of how to integrate custom payloads with Google Dialogflow ES bots. This script uses the VoicebotExchange action, but the process of integrating custom payload is the same.

Download this script.