Watson Virtual Assistant Specifics

Watson Specifics

BVR uses the Watson Assistant v2 API. To use a Watson Virtual Assistant with VXML, a VIRTUAL_ASSISTANT_WATSON Call Feature must be attached to the application. Information on the required parameters can be found in Parameters for VIRTUAL_ASSISTANT_WATSON Call Feature

Watson Assistant with VXML must be used with a separate STT Call Feature attached, such as STT_WATSON.

All examples in this document are using the Object format for the grammar rather than the JSON plaintext inline grammar format.

Dynamic Configuration

The Watson Assistant integration allows an application developer using VoiceXML to dynamically override the following Watson Assistant configuration parameters:

Service URL: Using the service_url_override
Assistant ID: Using the assistant_id_override
API key: Using the api_key_override

These are modified by setting values in the request object used to generate the Virtual Assistant grammar as in the following example:

        
         <assign name="virtual_assistant_request_structure.options" expr="new Object()"/>
         <assign name="virtual_assistant_request_structure.options.service_url_override" expr="'https://api.eu-gb.assistant.watson.cloud.ibm.com/instances/vwxyz'"/>
         <assign name="virtual_assistant_request_structure.options.assistant_id_override" expr="'wzyx'"/>
         <assign name="virtual_assistant_request_structure.options.api_key_override" expr="'1234'"/>
      
         <grammar mode="voice" version="1.0" type="application/x-blueworx-virtual-assistant+json" srcexpr="objectToJson(virtual_assistant_request_structure)"/>

Any values set prior to using the grammar will override those entries configured for the call feature.

Custom Variables (Inbound and Outbound)

In Watson, the custom_vars structure is sent as as part of the user_defined context structure to the Watson session. It is a simple freeform key/value pair map.

As an example for how to set these, if using the object format:


    <assign name="virtual_assistant_request_structure.custom_vars.custom_number" expr="2"/>
    <assign name="virtual_assistant_request_structure.custom_vars.custom_text" expr="'donuts'"/>
    <assign name="virtual_assistant_request_structure.custom_vars.custom_boolean" expr="true"/>

To get custom variables from the response, simply pull them from the shadow variable's interpretation, for example to log a custom variable my_variable:


    <log>My variable is <value expr="virtual_assistant_field$.interpretation.custom_vars.my_variable"/></log>

It is also possible to set/get the context in Watson using the virtual_assistant_request_structure.context structure. This will behave exactly the same as the custom_vars structure. Note that if both are supplied, they will be merged.

Example Watson response structure (JSON representation)

This is an example of the data structure format you can expect to see from a Watson response:


    {
        "transcript": "yes ",
        "messages": [
            {
                "text": "OK. Transferring..."
            }
        ],
        "message_text": "OK. Transferring...",
        "intents": [
            {
                "intent": "General_Greetings",
                "confidence": 0.22254178
            }
        ],
        "intent": {
            "intent": "General_Greetings",
            "confidence": 0.22254178
        },
        "entities": [
            {
                "entity": "reply",
                "value": "yes",
                "confidence": 1.0,
                "location": [
                    0,
                    3
                ]
            }
        ],
        "entity": {
            "entity": "reply",
            "value": "yes",
            "confidence": 1.0,
            "location": [
                0,
                3
            ]
        },
        "context": {
            "custom_boolean": "true",
            "custom_number": "2",
            "bw_no_match": false,
            "custom_text": "my text",
            "bw_action": "transfer"
        },
        "custom_vars": {
            "custom_boolean": "true",
            "custom_number": "2",
            "bw_no_match": false,
            "custom_text": "my text",
            "bw_action": "transfer"
        },
        "raw_json": "[raw json response from Watson Assistant goes here]"
    }

Configuring the Watson Assistant HTTP Request Timeout

It is possible to use the com.blueworx.watson_assistant.request_timeout property to configure the Watson Assistant HTTP request timeout (the amount of time BVR will wait before considering an HTTP request to the Watson Assistant API a failure). The value is a human readable time (e.g. "20 seconds"). If no time unit is specified, seconds will be used.


    <property name="com.blueworx.watson_assistant.request_timeout" value="5 seconds"/>