Custom Payload Snippet

The information on this help page applies to both Studio and Desktop Studio.

The Custom Payload snippet is required in your script when using actions that have the customPayload property, such as Voicebot Exchange or Textbot Conversation. It's used to pass data from CXone Mpower to your virtual agent A software application that handles customer interactions in place of a live human agent. provider. If you need to receive custom data from your virtual agent, use the customPayloadVarName (out) variable. Use the information on this page to create the Custom Payload snippet that meets the requirements of your organization's virtual agent implementation.

This snippet is required for the following virtual agents:

Amazon Lex V1 and Amazon Lex V2: The Custom Payload snippet is required for Lex V1 and Lex V2 even if you don't need to pass data to the virtual agent. The virtual agent uses the data passed through the customPayload property to populate the SessionAttributes property on the Amazon side.
Google Dialogflow ES: Custom payload passes context information that the Dialogflow ES virtual agent uses to determine intent The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish.. Follow the recommended best practices for integrating custom payload data with Google Dialogflow ES.

For all other virtual agents, you only need to include the snippet if you have custom payload data to pass to the bot. If you're using Dialogflow CX, follow the best practices for including custom payload. If you aren't including a custom payload snippet, be sure to pass a placeholder parameter.

Pass a Placeholder

If you use a virtual agent that doesn't need information passed to it, such as Amazon Lex V2 or Amazon Lex V1, follow this example:

DYNAMIC customPayload 
 customPayload.placeholder=""

Pass Data

For all virtual agent providers that must pass information to the virtual agent, follow this example. Replace the parameters in the example with the information you need to pass.

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

Google Dialogflow CX Custom Payload

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 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 Mpower. 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.
To pass custom data to Dialogflow CX from the script, use session_params in the customPayload object in a Snippet action. For example:
```
DYNAMIC customPayload
customPayload.session_params.name = "Winnie le Pooh" 
customPayload.session_params.job = "Food critic" 
customPayload.session_params.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.
Configure speech context hints and a custom conversation IDto transfer the conversation to a different Dialogflow CX virtual agent in the Custom Payload snippet.
When using VOICEBOT EXCHANGE: To configure how long the virtual agent waits when the contact pauses while speaking, add the maxPostEnergySilenceMSparameter to the Next Prompt Behaviorsor Default Next Prompt BehaviorsSnippet action.

Speech Context Hints for Dialogflow CX

Speech context hints can be passed in the Custom Payload snippet in the speechContexts parameter. The value of speechContexts.phrases must be a Google class token A square with an arrow pointing from the center to the upper right corner. 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

Configure these parameters as follows:

speechContexts.phrases: The Google class token for the hint you want to give. The token must match the language and locale of your contacts. If you want to add multiple tokens, add a speechContexts.phrases parameter for each token.
speechContexts.boost: A weighted numeric value between 1-20 to the specified phrase. The transcription service uses this value when selecting a possible transcription for words in the audio data. The higher the value, the greater the likelihood of the transcription service choosing that word or phrase from the alternatives.

You can see the contents of this parameter in Studio traces and application logs.

Transfer Contacts Between Dialogflow CX Virtual Agents

To set up transferring a contact from one Dialogflow CX virtual agent to another Dialogflow CX virtual agent, include the following line in the Custom Payload snippet. Replace custom_value with the variable name that holds the conversation ID:

{
  “cxone_override_conversation“: {custom_value} 
}

Be sure to set up your script to populate the variable you use with this parameter.

Your script must be set up carefully so that the

The cxone_override_conversation parameter is similar to the bot session state ID set in the Bot Session State snippet. Both help the virtual agent to maintain the context of the conversation between turns. Your script must be set up carefully so that the bot session state ID and conversation ID values appear in the correct locations. Bot session state always takes precedence over the cxone_override_conversation parameter. Set your script up as follows:

Virtual Agent #	Turn #	Configuration
1	1	The botSessionState property of the Voicebot EXCHANGE or Textbot EXCHANGE action is empty. The turn returns a bot session state ID and populates botSessionStateVarName (out). This is bot session state ID #1.
1	2 and later turns with this virtual agent	The script sends bot session state ID #1 to the Dialogflow CX virtual agent #1. The same ID is returned to the script.
2	3 (first with this virtual agent)	The botSessionState property of the Voicebot EXCHANGE or Textbot EXCHANGE action is empty. The custom payload snippet for this turn contains cxone_override_conversation = [variable]. The turn returns a unique bot session state ID and populates botSessionStateVarName (out), overriding any value it already contains. This is bot session state ID #2.
2	4 (second turn with this virtual agent)	The script sends bot session state ID #2 to the Dialogflow CX virtual agent #2. The same ID is returned to the script.

If you use more than two instances of Dialogflow CX, the pattern continues as established in the preceding table.

This method of transferring between virtual agents is only required when transferring between two or more Dialogflow CX virtual agents. If you're transferring between other virtual agent providers, you can use the Bot Session State ID.

Google Dialogflow ES Custom Payload

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.
Configure speech context hints in the Custom Payload snippet.

Speech Context Hints for Dialogflow ES

DYNAMIC customPayload
customPayload.speechContexts.phrases="$OOV_CLASS_ALPHANUMERIC_SEQUENCE"
customPayload.speechContexts.boost=10

Configure these parameters as follows:

speechContexts.phrases: The Google class token for the hint you want to give. The token must match the language and locale of your contacts. If you want to add multiple tokens, add a speechContexts.phrases parameter for each token.
speechContexts.boost: A weighted numeric value between 1-20 to the specified phrase. The transcription service uses this value when selecting a possible transcription for words in the audio data. The higher the value, the greater the likelihood of the transcription service choosing that word or phrase from the alternatives.

You can see the contents of this parameter in Studio traces and application logs.