wa-chat-server

Chat server based on the Watson Assistant API.

Configuration

Generally, we need to enter these environment variables to run an assistant:

• master_id – Master chatbot id.
• master_apikey – Master chatbot apikey.
• master_url – Assistant URL.
• master_timeout_ms – (optional) Timeout period in MS for calling chatbot.

In order to enable saving history of conversation, we have to set

• history_enabled – Enable history

The behaviour of conversation restart is controlled by

• soft_restart

On conversation restart the client sends the text input reset. With soft_restart === 'true' Watson is called with options.restart = true and reset is sent as a text input. Otherwise a new Watson session is created (the default option).

For swagger documentation, we have to set. Swagger documentation is located on URL/apidoc

• apidoc_enabled - Enable documentation

For a multiskill bot, we have to set

• routing_enabled – Enable routing.

and available child bots credentials

• childNUMBER_alias – Assistant alias. NUMBER can be actually any string alias, but we recommend to use a chatbot order.
• childNUMBER_id – Assistant id.

An example of such configuration could be

## Master assistant
master_id = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
master_apikey = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
master_url = https://gateway-fra.watsonplatform.net/assistant/api

# Child1 assistant
child1_alias = 'Child1'
child1_id = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# Child2 assistant
child2_alias = 'Child2'
child2_id = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# History enabled
history_enabled = true

# Routing enabled
routing_enabled = true

Here are some optional configurations:

• client_data_max_size_in_bytes - Set this property to a positive value if you would like to map data from the property client of the .../message API to the Watson context (property client). If the configured data size is exceeded then a warning is logged and no client data are mapped to the context.

• json_raw_body - Set this property to true to enable saving raw request body before parsing it to JSON. Generally used to validate request sender by comparing HMAC signature in adapters. Enabling this option will result in larger request size so consider using this feature only when required. Buffer containing the raw request body will be passed in rawBody attribute of the request.

Alternative authentication configurations:

IBM Cloud Pak For Data (CP4D) - If the Watson Assistant service is provided on-premise instead of IBM Cloud, there is an alternative authorization scheme using different set of credentials. Providing token_service_url will force initialization of CP4D authorization instead of IAM authorization. In this case the value master_apikey is not required.

• token_service_url - URL for the authorization endpoint that provides tokens. In standard CP4D installation it should be https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize.
• token_service_username - Username that is used for generating the token.
• token_service_password - Password that is used for generating the token. Not needed if token_service_apikey is provided.
• token_service_apikey - Apikey that is used for generating the token. When using apikey instead of password, token_service_username is still required - the apikey is generated for specific user. Not needed if token_service_password is provided.

Adapter Configuration

If there are some wa-chat-server adapters used in the deployment of the bot, the adapter configuration is placed on the same place as the wa-chat-server configuration (e. g. .env). The adapter specific directives are prefixed with adapter__[ADAPTER_NAME]__ (for example adapter__microsoft__appId).

LogDNA Logging

In order to use the LogDNA API for logging we need to set the following environment variables:

• logdna_key – Ingestion key for LogDNA.
• logdna_url – URL of the LogDNA API (ingestion endpoint, e. g. https://logs.eu-de.logging.cloud.ibm.com/logs/ingest).
• logdna_app – Name of the application (optional).
• logdna_app_hostname – Hostname of the application (optional).
• logdna_log_level – The log level (error, info, warn and debug). The default value is error.

If we configure LogDNA on local development instance (determined by the presence/absence of the VCAP_APP_PORT env. variable) then logs will be send to LogDNA as well as to the JavaScript console.

Shared Context

Context variables

$shared-PARAM

are shared with the whole router, which can thus affect its behaviour. This method populates the parameters in a non-routing way, i.e. there is no necessity for switching the dialog flow through the various chatbots.

For sharing parameters during routing, see attribute params in Routing from a master chatbot.

Routing

Routing allows us to pass the ongoing conversation from one chatbot to another. These are then distinguish into the master and child chatbots. Master chatbot may generally route to any child chatbot while the child chatbots may route only to the master, where is then decided what to do next.

The routing is determined by a context variable of a specific format, see Routing from a master chatbot and Routing from a child chatbot.

Routing from a master chatbot

The target context variable for routing has to be set to

$route-target = TARGET_CHATBOT_ALIAS

where TARGET_CHATBOT_ALIAS is an alias for the chatbot, defined in the application configuration.

There are some optional attributes that may be added to $route:

Attribute | Description --- | --- $route-intent | A name of a forced intent (always starting with the character #). $route-utterance | A forced utterance whose value is a context variable. If not specified, the assistant sends the user's last utterance. $route-params | An object of extra parameters that will be set using $route-params-PARAM1, $route-params-PARAM2 and temporarily stored for the target chatbot context as $incoming_route-params-PARAM1, $incoming_route-params-PARAM2, etc. For a permanent action, we should use $shared instead, see Shared Context for more details.

In order to determine the caller assistant, the integration provides

$incoming_route-origin

as a context variable for a master chatbot .

Routing from a child chatbot

We don't specify the target as the child chatbot always route to the master. Therefore the context variable is just set to

$route-target = [MASTER]

Similarly, as for the routing from master to child chatbot (see Routing from a master chatbot), there are the optional attributes intent and utterance as well.