Schemas

This page defines the schemas used in a custom virtual agent integration. Always refer to the CXone Swagger A square with an arrow pointing from the center outward. for custom virtual agent integrations to ensure you're using the most up-to-date version of the schema.

Request: ExternalIntegrationBotExchangeRequest

Parameter	Type	Description
virtualAgentId	String	The name given to the Custom Exchange Endpoint app in Virtual Agent Hub. This name identifies the virtual agent the app invokes.
botConfig	Object	A configuration object registered with the virtual agent.
userInput	String	The text input from the user received from the point of contact The entry point that an inbound contact uses to initiate an interaction, such as a phone number or email address. the script is assigned to.
userInputType	Enum	The user input type provided by the script. Possible values are: NO_INPUT, TEXT, BASE64_ENCODED_G711_ULAW_WAV_FILE, USER_INPUT_ARCHIVED_AS_SPECIFIED, USER_ENDED_SESSION, AUTOMATED_TEXT, DTMF_AS_TEXT
executionInfo	ActionExecutionInfo	Telemetry data for the execution of an action Performs a process within a Studio script, such as collecting customer data, playing a message or music, or routing a contact to an agent. within a script.
systemTelemetryData	SystemTelemetryData	Data that can be used for debugging. Contains information about the CXone infrastructure.
base64wavFile	String	Contains the Base 64-encoded WAV file that contains the header of the request.
botSessionState	Object	Can be used for round-trip session information variables received from the virtual agent.
customPayload	Object	Can be used to send additional variables and parameters from the context of the Studio script.
mediaType	String	Indicates the media type of the script that's running.

Request: ActionExecutionInfo

Contains information about the action and script being executed.

Parameter	Type	Details
contactId	Integer	The unique identifier for the interaction.
busNo	Integer	The ID of the CXonebusiness unit High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment where the script is located.
requestId	Integer	An iterative number that identifies each request in a particular interaction. If you include the requestId in requests, it can be included in the responses. This can help helpful for troubleshooting or other problem-solving. If requestID is a unique value, it can be used to locate a single request/response in log files.
actionType	String	The action type that makes the request to the custom endpoint.
actionId	Integer	The ID number of the Studio action within the script. Action IDs are based on the order the actions were added to the script.
scriptName	String	The path and name of the script making the request.

Request: SystemTelemetryData

Contains information about the action and script being executed.

Parameter	Type	Details
contactId	Integer	The unique identifier for the interaction.
busNo	Integer	The ID of the CXonebusiness unit High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment where the script is located.
requestId	Integer	An iterative number that identifies each request in a particular interaction. If you include the requestId in requests, it can be included in the responses. This can help helpful for troubleshooting or other problem-solving. If requestID is a unique value, it can be used to locate a single request/response in log files.
actionType	String	The action type that makes the request to the custom endpoint.
actionId	Integer	The ID number of the Studio action within the script. Action IDs are based on the order the actions were added to the script.
scriptName	String	The path and name of the script making the request.

Response: CustomExchangeResponse_V1

Parameter	Type	Description
branchName	Enum	The branch the script is to take. Can contain the following values: DoNotBegin, PromptAndCollectNextResponse, ReturnControlToScript, EndContact, AudioInputUntranscribeable, Error, DTMFBreakout, UserInputTimeout, UserInputNotUnderstood
nextPromptSequence	PromptSequence	Specifies the prompt sequence to be played for the contact. Can be used directly in a Play action.
intentInfo	IntentInfo	Can be used to populate information about the intent recognized by the endpoint in an integration that includes NLU This process expands on Natural Language Processing (NLP) to make decisions or take action based on what it understands..
nextPromptBehaviors	PromptBehaviors	Configuration for audio collection and silence control. For voice channel A way for contacts to interact with agents or bots. A channel can be voice, email, chat, social media, and so on. integrations only.
customPayload	Object	Can be used to send additional custom variables between the endpoint and CXone. This is a general container for any variable or parameters that the endpoint requires. Common use cases include: Authentication, to send security keys or tokens for validation at the endpoint. Custom reporting, to include custom metrics or computations to be used to generate KPIs An established metric used to measure agent performance and so on. More information about including custom payloads is available on the help pages for the Textbot Exchange action and the Voicebot Exchange action. { "param1": "value1" "param2": "value2" }
errorDetails	BotErrorDetails	Configurations for error handling, including how to prompt and handle errors in the script.
botSessionState	Object	Can be used to send session context variables that CXone maintains. You can learn more about this parameter on the Bot Session State help page.

Response: PromptSequence

Parameter	Type	Description
prompts	Array [PromptDefinition]	An array of thePromptDefinition objects, used to return multiple prompts from the endpoint. For voice interactions, the sequence can be a combination of text-to-speech and pre-recorded audio files.

Response: PromptDefinition

For more information about defining prompt sequences, see the Prompts help page.

Parameter	Type	Description
transcript	String	The virtual agent response text that will be displayed to the user in the chat or synthesized by STT Also called STT, this process converts spoken language to text..
base64EndcodedG711ulawWithWavHeader	String	The base64-encoded WAV file for the response from the endpoint, if the endpoint is capable of returning audio in the response to be played at the next turn. Audio responses must be in the µ-law G711 codec.
audioFilePath	String	Can be used by the endpoint to specify any audio file that exists in the NICE CXonetenant that is accessible and in the correct format to be played at the next turn.
textToSpeech	String	Can be used to send back to be synthesized by the CXone text-to-speech service.
mediaSpecificObject	Object	Contains the rich media content for an interaction taking place over a Digital Experience text-based channel A way for contacts to interact with agents or bots. A channel can be voice, email, chat, social media, and so on..

Response: IntentInfo

Parameter	Type	Description
intent	String	Use to send back the intent The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish that the NLU This process expands on Natural Language Processing (NLP) to make decisions or take action based on what it understands. component has identified in the contact's input.
context	String	Use to send back the context information or the name that the NLU component is actively using to handle the intent.
intentConfidence	String	Use to send back the confidence that the NLU component has determined for the intent.
lastUserUtterance	String	Use to hold the contact's last utterance. This parameter is sent through the proxy tunnel to the virtual agent, and is returned to CXone in the payload with the virtual agent's response. This parameter is useful during testing and debugging.
slots	Object	Use this object to send information or the values of slots (entities or parameters used with the intent).

Response: PromptBehaviors

More information about defining prompt behaviors in a Studio script is available on the Next Prompt Behaviors help page.

Parameter	Type	Description
silenceRules	SilenceRules	A configuration to allow control over timeout for specific parts of the conversation.
audioCollectionRules	AudioCollectionRules	A configuration to allow control over how audio is collected. Includes additional settings for DTMF collection.

Response: SilenceRules

Silence rules are a set of parameters defined as part of the prompt behaviors. More information about defining these rules in a Studio script is available on the Next Prompt Behaviors help page.

Parameter	Type	Description
engageComfortSequence	Boolean	Use to control whether a prompt is to be played when the endpoint processing might have a significant wait time after collecting the next user input from the contact. For example, you might have a prompt play for the contact that says "Please wait while I look this up for you."
botResponseDelayTolerance	Integer	Specifies the amount of time in milliseconds that the script should wait for the endpoint response. When the timeout is reached, the comfort sequence triggers. This parameter is used only if engageComfortSequence is set to true.
comfortPromptSequence	PromptSequence	Plays a number of prompts through base64EndcodedG711ulawWithWavHeader, audioFilePath, textToSpeech, or transcript. This parameter is used only if engageComfortSequence is set to true.
millisecondsToWaitForUserResponse	Integer	Use to specify how long in milliseconds the script should wait for the contact to respond. When this timeout is reached, the script sends a No_Input request to the endpoint.

Response: AudioCollectionRules

Audio collection rules are a set of parameters defined as part of the prompt behaviors. More information about defining these rules in a Studio script is available on the Next Prompt Behaviors help page.

Parameter	Type	Description
collectionType	Enum	Use to specify how to collect the contact's input on the next turn. Possible values are: DO_NOT_COLLECT_USER_RESPONSE, SEND_UTTERANCe_AUDIO, SEND_DTMF_ONLY_AS_TEXT
dtmfRules	CollectDtmfRules	Holds configuration settings for the collection of DTMF Signaling tones that are generated when a user presses or taps a key on their telephone keypad. tones.
bargeConfiguration	PromptBargeConfiguration	Holds configuration settings for barge-in behavior. Barge-in allows contacts to interrupt the prompt that's being played.

Response: CollectDtmfRules

DTMF collection rules are a set of parameters defined as part of the prompt behaviors. More information about defining these rules in a Studio script is available on the Next Prompt Behaviors help page.

Parameter	Type	Description
detectDtmf	Boolean	Controls whether DTMF tones are processed and acted on.
clearDigits	Boolean	Controls whether previously-detected DTMF tones should be cleared from the buffer.
terminationCharacters	String	Use to specify the character you want the contact to enter to indicate they've finished entering numbers. For example, the pound sign (#) is commonly used as a terminator.
stripTerminator	Boolean	Controls whether the terminator characters need to be concatenated in the contact input that's sent.
interDigitTimeoutMilliseconds	Integer	Use to specify how long in milliseconds the script waits between digits the contact enters.
maxDigits	Integer	Use to specify the maximum number of DTMF digits to be collected. If you are using a terminator, include it as one of the characters when you count the maximum number of digits.

Response: PromptBargeConfiguration

Barge is an option you can define as part of the prompt behaviors. More information about including this option in a Studio script is available on the Next Prompt Behaviors help page.

Parameter	Type	Description
enableSpeakerBarge	Boolean	Use to control whether the contact can barge in while a prompt is being played.

Response: AudioTranscriptionConfig

If you want to use CXone Turn-by-Turn Transcription instead of your virtual agent's default transcription service, use AudioTranscriptionConfig.

Parameter	Type	Description
transcriptionProfileId	String	Specifies the ID of an existing transcription profile. If you specify a profile here, it overrides the setting made in the Custom Exchange Endpoint app in Virtual Agent Hub.
hintPhrases	Array	Supply an optional list of phrases that can give hints to the transcription service. For example, you might include context models, product names, commonly used names or phrases, and so on.

Response: BotErrorDetails

Parameter	Type	Description
errorLoopBehavior	Enum	Use to control what the script does if the endpoint returns an error. Can contain the following values: ReturnControlToScriptThroughErrorBranch, EndContact
errorPromptSequence	PromptSequence	Use to have a prompt play for the contact in the event of an error.
systemErrorMessage	String	Use for debugging. Error message is visible in the Test window in the Custom Exchange Endpoints properties page in Virtual Agent Hub.