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 agentClosed 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: 

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 intentsClosed 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 actionaction 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 A square with an arrow pointing from the center out from the top right corner. 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 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		
  • When using VOICEBOT EXCHANGETo 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 intentClosed 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 utteranceClosed 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 documentationIcon indicating the link goes to an external website 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 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