VoiceBot Exchange

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

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

The Voicebot 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 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 the response to give. The action passes the virtual agent's response to the contact. When the conversation is complete, the action continues the script.

If you want to configure barge in or no input, additional scripting is required.

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

Dependencies

A script must contain at least two VoiceBot Exchange actions connected in a loop.
To use this action, your virtual agent must support turn-by-turn conversation customization.
A conversational turn is defined as:
1. The contact utterance being sent to the virtual agent.
2. The virtual agent processing the utterance and defining any custom payload information.
3. The answer passing back to the contact.
4. Any additional actions to be taken (such as a database or external API call) which are determined in the nextPromptBehaviors property. You can also configure the conversational loop to exit when the interaction is complete or if the contact is transferred to a live agent.
If you're including custom payload with Google Dialogflow ES or Google Dialogflow CX virtual agents, follow the custom payload best practices and guidelines. The guidelines for CX and ES are provided on this page.

Supported Script Types

The icon for the Phone script type - an old-style phone handset with curved lines indicating sound coming out of it.

Phone

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:

Amazon Lex V1
Amazon Lex V2
Google Dialogflow CX (only for utterance-based connections)
Google Dialogflow ES

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	Description
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.
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.
nextPromptSequence	The response received from the virtual agent that will be played for the contact. Configure this property with the variable specified in nextPromptSequenceVarName (out) with the asJSON() function. You can also convert the contents of nextPromptSequenceVarName (out) to JSON in a Snippet action and configure this property with the variable that holds the JSON.
nextPromptBehaviors	Specifies the configuration and behavior of the next prompt in a conversation. Define the behaviors you want to see using a Snippet action and following the Default Next Prompt Behaviors or Next Prompt Behaviors snippet example. This example describes properties you can use to configure comfort noise, DTMF collection, and allowing the contact to speak over audio as it's playing (barge). Configure the nextPromptBehavior property with the name of the object you used in the snippet code. This passes settings to this property and its action. For example, using the Next Prompt Behavior snippet example, you would enter {nextPromptBehaviorsOutjson} for this property. You only need to configure this property if using this action to enable a text virtual agent to handle voice interactions.
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.
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.

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
nextPromptBehaviorsVarName (out)	Defines the behaviors for prompting the user on the next conversational turn.
nextPromptSequenceVarName (out)	Holds the response from the virtual agent and passes it to the nextPromptSequence property.
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.
OnDTMFBreakout	Path taken when a DTMF Signaling tones that are generated when a user presses or taps a key on their telephone keypad. rule in the script was met.
OnUserInputTimeout	Path taken when there is no response by the user in the time specified in the Prompt Behavior snippet (either the Default or the Next Prompt Behavior snippet). For Google Dialogflow, you can configure the event that you want to happen in the Virtual Agent Hub Dialogflow app. For Dialogflow ES, configure the Timeout Event field. For Dialogflow CX, configure the Timeout Event Handler. If no event is configured, the default is to use the default fallback intent as configured in the Dialogflow console. If you want, you can configure this branch to use different events at different points in your script.
OnUserInputNotUnderstood	Path taken when the virtual agent doesn't understand the contact's response or when the contact times out.

Required 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 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 VOICEBOT EXCHANGE or TEXTBOT EXCHANGE 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		
```
To configure how long the virtual agent waits when the contact pauses while speaking, add the maxPostEnergySilenceMS parameter to the Next Prompt Behaviorsor Default Next Prompt Behaviors Snippet action.

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		
```

Tips and Tricks

If voice audio cannot be heard between Virtual Agent Hub and the virtual agent, check the script trace to see if there is a transcript. If there is, the Google Dialogflow virtual agent needs to be adjusted.

Script Example

This is an example to show how this action can be used in scripts. It is not intended to be a complete script. Additional scripting may be required.

VoiceBot Exchange actions must be used in a loop. This means that you must use at least two in a script. The first action initiates the call to the virtual agent's API and must be preceded by the Default Next Prompt Behavior Snippet action. The first action is the Welcome Default, which begins the first scripted loop, or one conversational 'turn'.

An example of a script that uses the VoicebotExchange action.

Download this script.

Example Script for CustomPayload with Google Dialogflow ES

This is an example to show how this action can be used in scripts. It is not intended to be a complete script. Additional scripting may be required.

This script is an example of how to integrate custom payloads with Google Dialogflow ES virtual agents. This script uses the Voicebot Exchange action, but it will also work if you use TEXTBOT EXCHaNGE instead.

An example script showing how to handle custom payload with Google Dialogflow CX.

Download this script.

Example Script for Alternate Timeout Events

This is an example to show how this action can be used in scripts. It is not intended to be a complete script. Additional scripting may be required.

You can use different timeout events at different points in your script. For example, you might want to use different timeout events the first and second times the UserInputTimeout property is triggered. This example script shows one possible way to make this happen.

In this script, Snippet actions are used to create and increment a timeout counter. After the second timeout, a Snippet action is used to set a different timeout event. The alternate timeout event is passed from the Snippet action to the voicebot action through the automatedIntent property.

Download this script.