Integration with IBM Watson Assistant

Blueworx Voice Response can connect to an IBM Watson Assistant using CCXML.

Using IBM Watson Assistant with BVR

Integrating a BVR CCXML application with Watson Assistant is achieved using a dialogstart with the src field specifying the IBM Watson Assistant service URL and the parameters field specifying other information required to connect to the Watson Assistant.

In order for an application to use IBM Watson Assistant, the application must have a call feature for TTS and a call feature for STT attached to it. See here for details: BAM Command Line Utility Call Features Panel

Along with the IBM Watson Assistant service URL to be used for the src parameter, the following CCXML variables must be set up for use with the dialogstart:

watson_assistant_id The alias for the bot to connect to. At the time of writing, an alias can be set up for a Watson Assistant bot in the Aliases section of the Settings tab in the IBM Cloud Web UI.
watson_api_key The API key for the Watson Assistant service.

The following optional parameters may also be supplied

bargein Whether or not to allow bargein during audio prompts. If not specified, this will default to true.
initial_speech_duration Determines the amount of speech (in milliseconds) that has to be detected before BVR starts sending audio to the attached STT service. Default value is 200ms.
final_silence_duration Determines the amount of silence (in milliseconds) required before user input to the attached STT service is considered complete. If not specified, this will default to 500ms.
initial_input_text If specified, BVR will send the text value of this variable to Watson Assistant when it first starts the dialog, which will behave as if the words were spoken to start with. If this is not specified, Watson Assistant will await voice input.

Once these variables have been setup, the IBM Watson Assistant dialog can be started with a dialogstart like the following:

<dialogstart src="watson_service_url" type="'application/watson-assistant'" connectionid="evt.connectionid" parameters="watson_assistant_id watson_api_key"/>

The provided sample application has an example of defining and using those variables.

The IBM Watson Assistant dialog finishes when the Watson Assistant bw_action context variable is set to an action that ends the dialog, such as "end_dialog" or "transfer"

Using context variables to control BVR

It is possible to trigger certain actions on BVR by setting context variables in your Watson Assistant application. These context variables can be set at any time on a dialog. For further information on setting context variables in Watson Assistant dialogs, please refer to the IBM Watson Assistant documentation.

The bw_action context variable

end_dialog Ends the current Watson Assistant dialog, triggering a CCXML dialog.exit transition
transfer Triggers the dialog.transfer CCXML transition and ends the dialog. It is possible to set a transfer target by setting the session variable "bw_transfer_target". Note: If setting "bw_transfer_target" to a SIP URI in a Watson Assistant dialog, it is important to note that the "@" character is reserved and must be escaped with "\\". For example, "sip:test\\@test.com". Further information on transferring in CCXML can be found on the CCXML Call Transfer and Bridging page.

Watson Assistant Exit Values

When a Watson Assistant dialog has finished, some values will be set to the "watson" property on the dialog.exit event values evt.values.watson. Within this object are the following values:

user_defined A map containing user defined values that were set in the Watson Assistant session
full_output A map containing a representation of the entirety of the output from the last message received from Watson Assistant.

Any variable names within these structures with a space character will have that space automatically replaced with an underscore '_' character

If the exit values contain any arrays, they will be presented as a map which contains a "count" property to determine the number of items in the array. Each item in the array will be a property of the map where the key is the index (starting from 0)

As an example, if the user_defined data from Watson Assistant contains an array called "custom data" with 2 entries, there will be the following values:

evt.values.watson.user_defined.custom_data.count The number of items in the array - in this case, the value for this will be 2
evt.values.watson.user_defined.custom_data.0 The first item in the array
evt.values.watson.user_defined.custom_data.1 The second item in the array

It is possible to loop through an array in CCXML. Here is an example of some Javascript code that can be added to a CCXML document in the <script> tag and invoked by calling printArray(arrayObject). This script relies on the existence of the printObject function

function printArray(toLog) {
       var output = "";

       if (toLog == null) {
          return "Cannot turn null object into an array";
       }
       var count = toLog.count;
       if (count == null) {
          return "This object is not an array";
       }
       //Total now has the last index value for the list of attributes in toPrint
       output += "Array has " + count + " items\n";
       var i;
       for (i = 0; i &lt; count; i++) {
          output += "\nItem " + i + ": " + toLog[i];
       }
       return output;
    }

Sample Applications

We have provided sample applications that describe the integration and can be used to connect to IBM Watson Assistant. The sample applications are installed on the BVR server in the following location:

/opt/blueworx/vr/sample/IBMWatsonAssistant

Debugging IBM Watson Assistant applications

Watson Assistant applications have a single trace component: WATSON_AST