Reporting Watson Assistant turn events from Voice Gateway

Configuring Voice Gateway to publish Watson Assistant turn events

1. Set up a Splunk HTTP Event Collector (HEC) or a REST server that can store the events, for example in a noSQL database.

2. In the Voice Gateway configuration, specify your REST server URL and authorization credentials and enable Watson Assistant turn events by setting the Watson Assistant turn event index value.

   • Single-tenant environment: Set the following environment variables in your configuration.

   REPORTING_URL=http://myresteventserver.ibm.com/
   REPORTING_USERNAME=myRestAdmin
   REPORTING_PASSWORD=myRestTokenOrPassword
   REPORTING_CONVERSATION_EVENT_INDEX=conv
     REPORTING_CONVERSATION_EVENT_SOURCE_TYPE=conversationID
   REPORTING_CONVERSATION_REQUEST_EVENT_INDEX=convRequest
   REPORTING_CONVERSATION_REQUEST_EVENT_SOURCE_TYPE=conversationID
   
   

   • Multi-tenant JSON configuration: In the multi-tenant JSON configuration file, for each tenant where you want to enable Watson Assistant turn events, configure a reporting object that contains the following properties. You can configure indexes for other types of events, such as transcription or call detail record events, within the same object.

   ...
   "reporting": {
     "url": "http://myresteventserver.ibm.com/",
     "username": "myRestAdmin",
     "password": "myRestTokenOrPassword",
     "convEventInd": "conv",
     "convEventSourceType" : "conversationID",
     "convRequestEventInd": "convRequest",
     "convRequestEventSourceType" : "conversationID"
   }
   ...
   

   The Watson Assistant event index value is included as the index value in all Watson Assistant turn events so that the REST server that consumes them can differentiate the type of event. The index field is required for Splunk HEC, but it's also useful for anyone who is building their own REST server to handle these events.

Configuring Voice Gateway to publish Watson Assistant turn events in an IBM Cloudant database

Before configuring Voice Gateway to publish to IBM Cloudant, set up a IBM® Cloudant® for IBM Cloud.

Set the following environment variables in your configuration to publish Watson Assistant turn events in an IBM Cloudant database. You can use both IBM Cloudant and another reporting service simultaneously by adding the IBM Cloudant configuration variables to your configuration.

The following examples show the configuration for publishing turn events to IBM Cloudant. You can configure authentication for IBM Cloudant either with an API key by adding the REPORTING_CONVERSATION_CLOUDANT_APIKEY variable or by username and password by adding REPORTING_CONVERSATION_CLOUDANT_USERNAME and REPORTING_CONVERSATION_CLOUDANT_PASSWORD.

• Single-tenant environment: Set the following environment variables in your configuration.

  REPORTING_CONVERSATION_CLOUDANT_USERNAME=myIBM Cloudant Username
  REPORTING_CONVERSATION_CLOUDANT_PASSWORD=myCloudantPassword
  REPORTING_CONVERSATION_CLOUDANT_DB_NAME=myCloudantDB
  REPORTING_CONVERSATION_CLOUDANT_EVENT_INDEX=conversation
  

  If you use non-default account configurations to IBM Cloudant, you might need to include additional environment variables. See REPORTING_CONVERSATION_CLOUDANT_URL and REPORTING_CONVERSATION_CLOUDANT_ACCOUNT in Reporting event configuration.

• Multi-tenant JSON configuration: In the multi-tenant JSON configuration file, for each tenant where you want to enable Watson Assistant turn events, configure a reporting object that contains the following properties. If you use non-default account configurations to IBM Cloudant, you might need to include additional environment variables. See convCloudant in Properties for the reporting object.

  ...
  "reporting": {
  "convCloudant": {
    "username": "myCloudantUsername",
    "password": "myCloudantPassword",
    "dbName": "myCloudantDB",
    "eventInd": "conversation"
  }
  }
  ...
  

* **Single-tenant environment:** Set the following environment variables in your [configuration](https://www.ibm.com/docs/en/voice-gateway?topic=reference-configuration-environment-variables).
```yaml

  {:codeblock}

  * **Multi-tenant JSON configuration**: You must configure the `url` and `apikey` configuration variables instead of `username` and `password`.

  ```json
...
"reporting": {
  "convCloudant": {
    "url": "http://myconversationcloudant.ibm.com/",
    "apikey": "a1b2c3d3fgh1jk1mn0",
    "dbName": "myCloudantDB",
    "eventInd": "conversation"
  }
}
...

{:codeblock}

Configuring Voice Gateway to publish Watson Assistant turn events in a CouchDB

To set up CouchDB, clone the repository and follow the instructions on GitHub. If you use CouchDB, you can't use an API key to authenticate.

Set the following environment variables in your configuration to publish Watson Assistant turn events in an CouchDB database. You can use both CouchDB and another reporting service simultaneously by adding the CouchDB configuration variables to your configuration.

The following examples show the configuration for publishing turn events to CouchDB.

• Single-tenant environment: Set the following environment variables in your configuration.

  REPORTING_CONVERSATION_CLOUDANT_URL="http://<svc-couchdb>:5984/"
  REPORTING_CONVERSATION_CLOUDANT_USERNAME=myCouchDBUsername
  REPORTING_CONVERSATION_CLOUDANT_PASSWORD=myCouchDBPassword
  REPORTING_CONVERSATION_CLOUDANT_DB_NAME=myCouchDB
  REPORTING_CONVERSATION_CLOUDANT_EVENT_INDEX=conversation
  

• Multi-tenant JSON configuration: In the multi-tenant JSON configuration file, for each tenant where you want to enable Watson Assistant turn events, configure a reporting object that contains the following properties. If you use non-default account configurations to IBM Cloudant, you might need to include additional environment variables. See convCloudant in Properties for the reporting object.

  ...
  "reporting": {
  "convCloudant": {
    "url": "http://<svc-couchdb>:5984/",
    "username": "myCouchDBUsername",
    "password": "myCouchDBPassword",
    "dbName": "myCouchDB",
    "eventInd": "conversation"
  }
  }
  ...
  

Watson Assistant turn event format

A Watson Assistant turn event is the complete JSON object received back from Watson Assistant after each HTTP transaction. The event also includes some additional metadata, which you can use to map all of the turn events to a specific call detail record. The event format is based on the Splunk HTTP Event Controller JSON format.

Important: Watson Assistant turn events include text transcriptions and other information that could potentially contain Protected Health Information (PHI), personally identifiable information (PII), or PCI Data Security Standard (PCI DSS) data. Therefore, it's critical that the consuming server properly stores these events to prevent exposure of personal information.

In the following example, the initial part of the reporting event contains the keys for the Voice Gateway. The keys for the event JSON object are completely defined by the Watson Assistant service. For details, see the API reference for Watson Assistant.

Voice Gateway delivers Watson Assistant turn events in the exact form that they are received from Watson Assistant.

  {
      "time": 1434567892.516,
      "host": "vgw1.ibm.com",
      "source": "a23de67h-f41b-47b4-a8dc-e1c32b925b79",
      "sourcetype": "conversationID",
      "index": "conv",
      "event": {
                "input": {
                  "text": "Turn on the lights"
                },
                "context": {
                  "conversation_id": "a23de67h-f41b-47b4-a8dc-e1c32b925b79",
                  "system": {
                    "dialog_stack": [
                      {
                        "dialog_node": "root"
                      }
                    ],
                    "dialog_turn_counter": 2,
                    "dialog_request_counter": 2
                  },
                  "defaultCounter": 0
                },
                "entities": [
                  {
                    "entity": "appliance",
                    "location": [12, 18],
                    "value": "light"
                  }
                ],
                "intents": [
                  {
                    "intent": "turn_on",
                    "confidence": 0.99
                  }
                ],
                "output": {
                 "log_messages": [],
                  "text": [
                    "Ok. Turning on the light."
                  ],
                  "nodes_visited": [
                    "node_1_1467221909631",
                    "node_2_1467232480480"
                  ]
              }
          }        
      }

When Voice Gateway is configured to generate conversation events prior to sending requests to Watson Assistant, it delivers Watson Assistant turn events in the exact form that they are sent to Watson Assistant.

{
  "time": 1560524055.816,
  "host": "vgw1.ibm.com",
  "source": "sip:alice@example.com",
  "sourcetype": "sipURI",
  "index": "convRequest",
  "event": {
    "alternateIntents": false,
    "input": {
      "text": "1"
    },
    "context": {
      "vgwIsDTMF": "Yes",
      "global": {
        "vgwPostResponseTimeout": 1000
      },
      "vgwSIPCallID": "7DnGPA3SOw",
      "vgwTranscriptionSource": "sip:alice@example.com",
      "vgwSIPRequestURI": "sip:vgw@vgw1.ibm.com;transport=tcp",
      "system": {
        "initialized": true,
        "dialog_stack": [
          {
            "dialog_node": "root"
          }
        ],
        "dialog_turn_counter": 2,
        "dialog_request_counter": 2,
        "_node_output_map": {
          "Welcome": [
            0
          ],
          "Anything else": [
            0
          ]
        },
        "branch_exited": true,
        "branch_exited_reason": "fallback"
      },
      "vgwBargeInOccurred": "Yes",
      "conversation_id": "1eec7181-6424-4066-9f36-f6725574af5a",
      "vgwPostResponseTimeout": 1000,
      "vgwIsCaller": "Yes",
      "vgwCompletedActions": [
        {
          "command": "vgwActPlayText",
          "parameters": {
            "text": [
              "I didn't understand. You can try rephrasing."
            ]
          },
          "processed": true
        }
      ],
      "vgwSessionID": "7DnGPA3SOw",
      "vgwDTMFCollectionSucceeded": "Yes"
    }
  }
}