Integration with IBM Watson Assistant

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. Alternatively, the Watson Assistant can be determined by VIRTUAL_ASSISTANT_WATSON Call Features by setting the src parameter to "use_call_features", in which case none of the other parameters (such as watson_api_key) are necessary

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:

The following optional parameters may be supplied

Additional more complex parameters can be supplied in the hints

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"/>
            

Alternatively, to use VIRTUAL_ASSISTANT_WATSON Call Feature definitions:

<dialogstart src="'use_call_features'" type="'application/watson-assistant'" connectionid="evt.connectionid"/>
            

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"

​

Sending custom context variables from BVR to Watson Assistant

BVR sets some context variables by default. These are:

It is also possible to send custom context variables on the first message sent to the Watson Assistant session. These can be supplied as an object called "watson_custom_context_vars" in supplied hints when starting the dialog.

      <!-- Create the hints object -->
      <var name="watson_hints" expr="new Object()"/>
      <!-- Create the custom context variabled object that will contain all custom context variables we want to send to Watson Assistant -->
      <var name="watson_custom_context_obj" expr="new Object()"/>
      <!-- Setup some custom context variables -->
      <assign name="watson_custom_context_obj.my_variable" expr="'some value'"/>
      <assign name="watson_custom_context_obj.my_other_variable" expr="'some other value'"/>
      <!-- Set these custom context variables to the hints object under the name watson_custom_context_vars -->
      <assign name="watson_hints.watson_custom_context_vars" expr="watson_custom_context_obj"/>

      <!-- Now supply these hints when starting the dialog -->
      <dialogstart src="watson_service_url" type="'application/watson-assistant'" connectionid="evt.connectionid" parameters="watson_assistant_id watson_api_key" hints="watson_hints"/>
         

​

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

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:

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:

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 < count; i++) {
          output += "\nItem " + i + ": " + toLog[i];
       }
       return output;
    }
         

​

Example hints usage

The hints structure can be used to pass more complex objects to the Watson Assistant or to the STT engine. Below is an example of a hints structure that sets the context variable "my_variable" and sets the "end_of_phrase_silence_time" parameter on the STT engine. Note that the STT parms are platform specific. In this case, we are using the IBM STT cloud service and setting the "end_of_phrase_silence_time" to 0.4 seconds. For all available parameters please refer to the IBM STT Websockets API documentation. Note that URL parameters and message body parameters can both be used in the stt_parms structure for IBM STT. If the model parameter is set in stt_parms it will override the model in the call feature definition.

 
<!-- Create the hints object -->
<var name="watson_hints" expr="new Object()"/>

<!-- Create the custom context object -->
<var name="customcontext" expr="new Object()"/>

<!-- Set the "my_variable" parameter in the custom context object -->
<assign name="customcontext.my_variable" expr="'test value'"/>
                  
<!-- Assign the custom context object to the hints -->
<assign name="watson_hints.watson_custom_context_vars" expr="customcontext"/>

<!-- Create the STT parameters object -->
<var name="stt_parms" expr="new Object()"/>
                  
<!-- Set the "end_of_phrase_silence_time" parameter to 0.4 seconds in the STT parameters -->
<assign name="stt_parms.end_of_phrase_silence_time" expr="'0.4'"/>
                  
<!-- Assign the stt parameters to the hints -->
<assign name="watson_hints.stt_parms" expr="stt_parms"/>
                  
                  
<!-- Supply the hints on the dialogstart -->
<dialogstart src="watson_service_url" type="'application/watson-assistant'" connectionid="evt.connectionid" parameters="watson_assistant_id watson_api_key" hints="watson_hints"/>
         

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