Custom Payload Snippet

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

Use this snippet with actions that have the customPayload property, such as Voicebot Exchange or Textbot Conversation. It's used to pass data from CXone 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.

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.

Pass a Placeholder

If you use Amazon Lex V1 or Amazon Lex V2 and don't need to pass information to the virtual agent, follow this example:

DYNAMIC customPayload 
 customPayload.placeholder=""

If you need to pass information to the virtual agent, follow the example in the next section.

Pass Data

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


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

Best Practices for 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 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		
```
When using VOICEBOT EXCHANGE: 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 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.
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		
```