Schemas
This page defines the schemas used in a custom virtual agent integration. Always refer to the CXone Swagger 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:
More information about including custom payloads is available on the help pages for the Textbot Exchange action and the Voicebot Exchange action. { "param1": "value1" } |
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 CXone |
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 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. |