|
Integrates a self-service virtual agent
Voicebot Exchange monitors the conversation between the contact and the bot turn by turn. It sends each utterance Double-clicking this action opens the CXone Virtual Agent Hub, where you can manage all of your virtual agent bots. |
Supported Script Types
|
| Phone |
Related Studio Actions
The Voicebot 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.
Textbot Conversation and Textbot Exchange are also similar, providing the same functions as Voicebot Conversation and Voicebot Exchange, but for text-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. |
| 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 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. |
| nextPromptSequence |
Determines the order in which audio prompts are played by the action. The audio can be pre-recorded or TTS "{promptPath}Prompt1_{lang}.wav" "%{exampleVar}" "{promptPath}Prompt2_{lang}.wav" You can include different types of information in the prompt sequence. You can:
TTS has a 300 character limit. This property is similar to the Sequence property of the Play action. For voicebots. the sequence can be a mix of TTS |
| 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 defaultNextPromptBehaviors 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 variable from the Snippet action code that passes settings to this property and its action. For example, using the defaultNextPromptBehaviors Snippet code example, you would enter {nextPromptBehaviorsOutjson} for this property. |
| 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. |
| 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. |
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. |
| OnDTMFBreakout |
Path taken when a DTMF |
| OnUserInputTimeout |
Path taken when there is no response by the user in the time specified in the Default Next Prompt Behavior Snippet action. See the script example in this topic or Virtual Agent Hub for more information on the snippets required to set up a bot in Studio. |
| OnUserInputNotUnderstood |
Path taken when the user's intent is not matched by the bot. The Default Fallback Intent property is used for Google Dialogflow ES when the intent is not matched. |
Output Variables
| Variable | Details |
|---|---|
| nextPromptBehaviorsVarName (out) |
Defines the behaviors for prompting the user on the next conversational turn. |
| nextPromptSequenceVarName (out) |
Defines the next sequence prompts from the bot in 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. |
| botSessionStateVarName (out) |
References the botSessionState property. The botSessionState identification number is passed back as a bot parameter to maintain a session of the current conversation. |
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 code snippet
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:
If you want to pass information to the bot, follow this example:
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"
nextPromptBehavior/defaultNextPromptBehavior
View nextPromptBehavior/defaultNextPromptBehavior code snippet
This code specifies the behavior of another action. Use it with virtual agent A software application that handles customer interactions in place of a live human agent. actions to define behaviors for bots such as Google Dialogflow ES. You can include more than one Snippet action with this code in a single script. Each instance of the action can provide different behaviors to reflect what you want to happen at that point in the script.
The behaviors you can define are comfort noise, capturing DTMF Signaling tones that are generated when a user presses or taps a key on their telephone keypad.tones, and barge.
Click to view an example of this snippet
DYNAMIC defaultNextPromptBehaviors
ASSIGN defaultNextPromptBehaviors.silenceRules.engageComfortSequence="false"
ASSIGN defaultNextPromptBehaviors.silenceRules.botResponseDelayTolerance=1000
ASSIGN defaultNextPromptBehaviors.silenceRules.comfortPromptSequence.prompts[1].audioFilePath="comfortDEV.wav"
ASSIGN defaultNextPromptBehaviors.silenceRules.millisecondsToWaitForUserResponse=10000
ASSIGN defaultNextPromptBehaviors.audioCollectionRules.collectionType="SEND_UTTERANCE_AUDIO"
ASSIGN defaultNextPromptBehaviors.audioCollectionRules.dtmfRules.detectDtmf=false
ASSIGN defaultNextPromptBehaviors.audioCollectionRules.dtmfRules.clearDigits="true"
ASSIGN defaultNextPromptBehaviors.audioCollectionRules.dtmfRules.terminationCharacters="#"
ASSIGN defaultNextPromptBehaviors.audioCollectionRules.dtmfRules.stripTerminator=true
ASSIGN defaultNextPromptBehaviors.audioCollectionRules.dtmfRules.interDigitTimeoutMilliseconds=5000
ASSIGN defaultNextPromptBehaviors.audioCollectionRules.dtmfRules.maxDigits=10
ASSIGN defaultNextPromptBehaviors.audioCollectionRules.bargeConfiguration.enableSpeakerBarge="true"
ASSIGN defaultNextPromptBehaviors.userInputType=2
ASSIGN nextPromptBehaviorsOutjson="{defaultNextPromptBehaviors.asjson()}"
Properties for Comfort Noise
Comfort noise is audio that plays when the bot's response is delayed. Its purpose is to reassure the contact that the line is still active.
View comfort noise properties
| Property | Details |
|---|---|
| engageComfortSequence | Set the property to true if you want to enable comfort noise for this action. Set it to false if you don't want this action to use comfort noise. |
| botResponseDelayTolerance | Enter the amount of time in milliseconds that triggers the comfort noise audio file. |
| audioFilePath | Enter the location of the comfort noise audio file. The file should be located in your tenant's file structure. Include the whole path if the file is in a folder. The file structure is enforced as it would be for other prompt behavior. |
| millisecondsToWaitForUserResponse | Enter the amount of time in milliseconds that the action waits for a response from the contact before timing out. |
Properties for DTMF Detection
DTMF detection allows you to collect the tones when a contact presses buttons on the phone keypad.
View DTMF detection properties
| Property | Details |
|---|---|
| detectDtmf | Set this property to true if you want the action to capture DTMF entries. |
| clearDigits |
Set this property to true if you want to clear the DTMF tone buffer when the action begins. The buffer caches DTMF tones when the contact presses a key on their phone keypad. This property is similar to the clearDigitsproperty in the Menu action. |
| terminationCharacters |
Enter the character that you want contacts to enter to indicate they are finished entering digits. For example, you might want contacts to press the pound sign (#) when they finish entering an account number. This property is similar to the Terminationproperty in the Menu action. |
| stripTerminator | Set this property to true if you want to remove the value of the termination character from the captured DTMF tones. |
| interDigitTimeoutMilliseconds |
Enter the amount of time in milliseconds that the system waits after a contact enters a digit to determine if the contact will enter another digit. This property is similar to the InterDigitTimeoutproperty in the Menu action. |
| maxDigits |
Enter the maximum number of digits that the contact can enter for this action's prompt. For example, if the prompt instructs the contact to enter the last four digits of their social security number, set this property to 4. When the maxDigits value is reached, the script continues to execute. This property is similar to the MaxDigits property in the Menu action. |
Property for Barge
Barge allows the contact to speak over the audio that the script is playing.
View property for barge
| Property | Details |
|---|---|
| enableSpeakerBarge | Set this property to true to enable barge. This property should be enabled (true) for most bot interactions, but can be disabled (false) when the audio contains information the caller is required to hear, such as legal disclaimers. |
nextPromptSequence
View nextPromptSequence code snippet
Use this code with actions that have the nextPromptSequence property. This code specifies the general voice rules for receiving a prompt from the bot Virtual agent designed to handle specific interactions.
DYNAMIC nextPromptSequence
nextPromptSequence.prompts[1].transcript="ACTION - Next Prompt Sequence"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
- 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.
View example script for integrating custom payload
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.
Example Script Using VoiceBot Exchange
VoiceBotExchange 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'. A turn consists of:
- The contact utterance being sent to the virtual agent.
- The virtual agent processing the utterance and defining any custom payload information.
- The answer passing back to the contact.
- Any additional actions to be taken (such as a database or external API call) which are determined in the nextPromptBehaviors property. You can also determine the conversational loop to exit upon interaction completion or transfer to a live agent.
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.