Contribute in GitHub:

Dynamically configuring the Watson Assistant service or service orchestration engine

By using the IBM® Voice Gateway API, you can dynamically configure the IBM Watson™ Assistant service or service orchestration engine during a call. To change the configuration, define the vgwActSetConversationConfig action in the output of a node response in your Watson Assistant dialog tree. For more information about using the API, see Defining action tags and state variables.

Note: By default, Watson Assistant service instances that are not part of Premium plans log requests and their results to improve the service for future users. To prevent IBM usage of data in this way, see Data collection in the Watson Assistant API reference.

The attributes that you can define for the vgwActSetConversationConfig action each correspond with a SIP Orchestrator configuration environment variable. If an attribute isn't defined in Watson Assistant, the value from the related environment variable is used.

Important: The vgwActSetConversationConfig action and the vgwActSetWVAConfig action can't both be defined in an action sequence. Only a single Watson Assistant workspace chatbot can be configured at any one time.

See the following sections for examples of defining the vgwActSetConversationConfig action: * Watson Assistant service * Service orchestration engine

Watson Assistant service

The following example shows how to define a Watson Assistant workspace.

{
  "output": {
    "vgwAction": {
      "command": "vgwActSetConversationConfig",
      "parameters": {
        "url":"https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}",
        "workspaceID":"a23de67h-4e92-4565-c1b5-ebd59a2ffcad",
        "apikey": "PqxxxxrbuJ2ZxxxjZfyYe5oNRdY6AWdTa_xxxxEHVwCq"
      }
    }
  }
}

Table 1. Attributes for Watson Assistant
Attribute	Description	Related environment variable
`url`	The `url` credential for the Watson Assistant API.	`WATSON_CONVERSATION_URL`
`workspaceID`	The Workspace ID for the Watson Assistant API.	`WATSON_CONVERSATION_WORKSPACE_ID`
`username`	The `username` credential for Watson Assistant.	`WATSON_CONVERSATION_USERNAME`
`password`	The `password` credential for Watson Assistant.	`WATSON_CONVERSATION_PASSWORD`

Dynamically configuring multiple Watson Assistant services

You can define multiple providers in either the deployment configuration or the vgwActSetConversationConfig command. If a failure occurs on the first turn to a Watson Assistant workspace, then Voice Gateway tries to connect to the next defined provider in the list. This does not occur for subsequent turns to the same workspace because the context would be invalid. See Configuring multiple Watson Assistant service providers for more information about attributes of the providers properties.

The following example shows two providers configured in the vgwActSetConversationConfig command. If the first provider, nyc fails on the first turn, Voice Gateway changes to the second, dallas. The dallas provider has token authentication enabled, while nyc has basic authentication enabled.

{
  "vgwActSetConversationConfig": {
    "command": "vgwActSetConversationConfig",
    "parameters": {
      "providers": [
        {
          "name": "nyc",
          "url": "https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}",
          "apikey": "PqxxxxrbuJ2ZxxxjZfyYe5oNRdY6AWdTa_xxxxEHVwCq",
          "workspaceID": "e6f9e3e2-c27a-49e7-a8ac-d9a8ace43981"
        },
        {
          "name": "dallas",
          "url": "https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}",
          "apikey": "PqxxxxrbuJ2ZxxxjZfyYe5oNRdY6AWdTa_xxxxEHVwCq"
        }
      ]
    }
  }
}

Service orchestration engine

Because configuring a service orchestration engine uses the same environment variables as configuring Watson Assistant, you also change this configuration on the vgwActSetConversationConfig action.

Important: If you switch between a directly configured Watson Assistant service and a service orchestration engine, set the workspaceID attribute to an empty value to so that the configuration does not use the value from the configuration.

{
  "output": {
    "vgwAction": {
      "command": "vgwActSetConversationConfig",
      "parameters": {
        "url":"https://soe-example.net",
        "username":"adminuser",
        "password":"XgUCZZItgZD0"
      }
    }
  }
}

Table 2. Attributes for connecting to a service orchestration engine
Attribute	Description	Related environment variable
`url`	The exact URL to the service orchestration engine.	`WATSON_CONVERSATION_URL`
`workspaceID`	If switching from a Watson Assistant service, set to `""` to clear the workspace configuration.	`WATSON_CONVERSATION_WORKSPACE_ID`
`username`	The plain-text user name for the service orchestration engine. Required only if authentication is enabled in the SOE.	`WATSON_CONVERSATION_USERNAME`
`password`	The plain-text password for the service orchestration engine. Required only if authentication is enabled in the SOE.	`WATSON_CONVERSATION_PASSWORD`

Deprecated: Configuring Watson Assistant using state variables

In Version 1.0.0.2, configuring Watson services by defining state variables was deprecated in favor of the action tags described in the previous sections.

Important: Although the state variables continue to function, you can't define these deprecated state variables and the action tags within a node. Your Watson Assistant dialog can contain a mixture of action tags and deprecated state variables, but the JSON definition for each node can contain only one or the other.

{
	"context": {
		"vgwConversationConfigSettings": {
			"url": "https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}",
			"workspaceID": "a23de67h-4e92-4565-c1b5-ebd59a2ffcad",
			"apikey": "{apikey}",
			"tokenServiceProviderUrl": "https://iam.cloud.ibm.com/identity/token"
		}
	}
}

Table 3. JSON properties for Watson Assistant
JSON property	Description	Related environment variable
`url`	The `url` credential for the Watson Assistant API.	`WATSON_CONVERSATION_URL`
`workspaceID`	The Workspace ID for the Watson Assistant API.	`WATSON_CONVERSATION_WORKSPACE_ID`
`username`	The `username` credential for Watson Assistant.	`WATSON_CONVERSATION_USERNAME`
`password`	The `password` credential for Watson Assistant.	`WATSON_CONVERSATION_PASSWORD`