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 contactClosed 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 actionClosed 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 unitClosed 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 unitClosed 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 NLUClosed 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 channelClosed 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: 

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 STTClosed 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 CXonebusiness unit 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.

Response: IntentInfo

Parameter

Type

Description

intent String Use to send back the intentClosed The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish that the NLUClosed 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 DTMFClosed 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.