Botium Connector for Google Dialogflow

This is a Botium connector for testing your Dialogflow Agents.

Did you read the Botium in a Nutshell articles ? Be warned, without prior knowledge of Botium you won't be able to properly use this library!

How it works ?

Botium runs your conversations against the Dialogflow API.

It can be used as any other Botium connector with all Botium Stack components:

Extracts Button, Media, Card, and NLP information (intent, entities) from Chatbot API response. Accordingly it is possible to use a corresponding Botium Asserter.

Requirements

Node.js and NPM
a Dialogflow agent, and user account with administrative rights
a project directory on your workstation to hold test cases and Botium configuration

Install Botium and Dialogflow Connector

When using Botium CLI:

> npm install -g botium-cli
> npm install -g botium-connector-dialogflow
> botium-cli init
> botium-cli run

When using Botium Bindings:

> npm install -g botium-bindings
> npm install -g botium-connector-dialogflow
> botium-bindings init mocha
> npm install && npm run mocha

When using Botium Box:

Already integrated into Botium Box, no setup required

Connecting Dialogflow Agent to Botium

Open the file botium.json in your working directory and add the Google credentials for accessing your Dialogflow agent. This article shows how to retrieve all those settings.

{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "dialogflow",
      "DIALOGFLOW_PROJECT_ID": "<google project id>",
      "DIALOGFLOW_CLIENT_EMAIL": "<service credentials email>",
      "DIALOGFLOW_PRIVATE_KEY": "<service credentials private key>"
    }
  }
}

To check the configuration, run the emulator (Botium CLI required) to bring up a chat interface in your terminal window:

> botium-cli emulator

Botium setup is ready, you can begin to write your BotiumScript files.

Using the botium-connector-dialogflow-cli

This connector provides a CLI interface for importing convos and utterances from your Dialogflow agent and convert it to BotiumScript.

Intents and Utterances are converted to BotiumScript utterances files (using the --buildconvos option)
Conversations are reverse engineered and converted to BotiumScript convo files (using the --buildmultistepconvos option)

You can either run the CLI with botium-cli (recommended - it is integrated there), or directly from this connector (see samples/assistant directory for some examples):

> botium-connector-dialogflow-cli import --buildconvos
> botium-connector-dialogflow-cli import --buildmultistepconvos

Please note that you will have to install the npm packages botium-core manually before using this CLI

For getting help on the available CLI options and switches, run:

> botium-connector-dialogflow-cli import --help

Dialogflow Context Handling

When using BotiumScript, you can do assertions on and manipulation of the Dialogflow context variables.

Asserting context and context parameters

For asserting existance of context variables, you can use the JSON_PATH asserter:

Assert output context name

#bot
JSON_PATH $.outputContexts[0].name|*testsession*

Use the ***** for wildcard matching

Assert context parameter "myparameter" for output context named "mycontext"

#bot
JSON_PATH $.outputContexts[?(@.name.indexOf('mycontext') >= 0)].parameters.myparameter|somevalue

Use the JSONPath filer for matching a context by name instead of index

Assert lifespan for output context named "mycontext"

#bot
JSON_PATH $.outputContexts[?(@.name.indexOf('mycontext') >= 0 && @.lifespanCount > 2)]

Adding context variables

For adding a context variable, you have to use the UPDATE_CUSTOM logic hook. This example will set two context variables, one with some parameters:

#me
heyo
UPDATE_CUSTOM SET_DIALOGFLOW_CONTEXT|mycontext1|7
UPDATE_CUSTOM SET_DIALOGFLOW_CONTEXT|mycontext2|{"lifespan": 4, "parameters": { "test": "test1"}}

The parameters are:

SET_DIALOGFLOW_CONTEXT
The name of the context variable (if already existing, it will be overwritten)
The lifespan of the context variable (if scalar value), or the lifespan and the context parameters (if JSON formatted)

Dialogflow Query Parameters

When using BotiumScript, you can do manipulation of the Dialogflow query parameters.You have to use the UPDATE_CUSTOM logic hook. This example will add a payload field with some JSON content in the query parameters:

#me
heyo
UPDATE_CUSTOM SET_DIALOGFLOW_QUERYPARAMS|payload|{"key": "value"}

Supported Capabilities

Set the capability CONTAINERMODE to dialogflow to activate this connector.

DIALOGFLOW_PROJECT_ID

Google project id. See This article

DIALOGFLOW_ENVIRONMENT

Dialogflow publishing environment name. See This article

DIALOGFLOW_CLIENT_EMAIL

Optional

Google client email. See This article

If not given, Google default authentication will be used.

DIALOGFLOW_PRIVATE_KEY

Optional

Google private key. See This article

If not given, Google default authentication will be used.

DIALOGFLOW_LANGUAGE_CODE

The language of this conversational query. See all languages. A Dialogflow Agent is multilingiual, Connector is not. But you can use more botium.json for each language. (Botium Box, or Botium CLI is recommended in this case. Botium Bindings does not support more botium.xml)

DIALOGFLOW_OUTPUT_PLATFORM

Set the chat platform to get platform dependent response. See all platforms If you have multi platform dependent conversation, then it is the same situation as DIALOGFLOW_LANGUAGE_CODE

DIALOGFLOW_FORCE_INTENT_RESOLUTION

Experimental capability.

From a Dialogflow response the Connector can extract zero, one, or more messages. Every message will got the NLP information like intent and entities from the Dialogflow response. If Connector extracts zero messages, then creates a dummy one, to hold the NLP information. With this flag you can turn off this feature.

Default true

DIALOGFLOW_BUTTON_EVENTS

Default true

Botium simulates button clicks by using Dialogflow "Events". If the payload of the button click simulation is valid JSON, it should include a "name" and a "parameters" attribute, otherwise the named event without parameters is triggered.

By setting this capability to false this behaviour can be disabled and a button click is sent as text input to Dialogflow.

DIALOGFLOW_QUERY_PARAMS

Setting the initial Dialogflow query parameters.

Has to be a JSON-string or JSON-object.

DIALOGFLOW_INPUT_CONTEXT_NAME(_X)

You can use Contexts. They can be useful if you dont want to start the conversation from beginning, or you can set a context parameter “testmode” to make the web api behind the fulfillment react in a different way than in normal mode.

If you are using more context parameters then you have to use more Capabilities. Use a name, or number as suffix to distinguish them. (Like DIALOGFLOW_INPUT_CONTEXT_NAME_EMAIL).

This Capability contains the name of the parameter.

DIALOGFLOW_INPUT_CONTEXT_LIFESPAN(_X)

The number of queries this parameter will remain active after being invoked.

Mandatory Capability.

DIALOGFLOW_INPUT_CONTEXT_PARAMETERS(_X)

This Capability contains the values of the parameter. It is a JSON structure. See Sample botium.json

Optional Capability.

DIALOGFLOW_ENABLE_KNOWLEDGEBASE

Default: false

This Capability enables support for Dialogflow Knowledge Connectors. If this is set to true, then all knowledge bases connected to your Dialogflow agent are included in the queries. You can select individual knowledge bases by using a JSON array with the full knowledge base names, including the google project id and the knowledge base id:

...
"DIALOGFLOW_ENABLE_KNOWLEDGEBASE": [ "projects/project-id/knowledgeBases/knowledge-base-id" ]
...

DIALOGFLOW_FALLBACK_INTENTS

Default: ['Default Fallback Intent']

As default the not recognized utterance will be categorized as Default Fallback Intent by Dialogflow. If you change this behavior, you can inform connector about it. Used just for analyzation.

Additional Capabilities for NLP Analytics

The recommendation is to separate the Dialogflow agent you are using for NLP analytics from the one used for training your chatbot. There is a separate set of capabilities for connecting to an additional Dialogflow agent.

DIALOGFLOW_NLP_PROJECT_ID

Google project id.

DIALOGFLOW_NLP_CLIENT_EMAIL

Google client email.

DIALOGFLOW_NLP_PRIVATE_KEY

Google private key.

Additional Capabilities for Audio Input (Speech Recognition)

For more details about audio configuration, go here.

DIALOGFLOW_AUDIOINPUT_ENCODING

Audio File Encoding

DIALOGFLOW_AUDIOINPUT_SAMPLERATEHERTZ

Audio File Sample Rate in Hertz

DIALOGFLOW_AUDIOINPUT_CHANNELS

Audio File - Count of Channels

DIALOGFLOW_AUDIOINPUT_RECOGNITION_PER_CHANNEL

Audio File - Separate Recognition per Channel

DIALOGFLOW_API_ENDPOINT

By default the Dialogflow connector only works with the US (Global) region of Dialogflow, however it can be configured to connect to a region specific version of Dialogflow. This requires setting the project ID to include the location AND setting a custom API Endpoint for the specific region dialogflow instance. In this example configuration, an example of the dialogflow region would be australia-southeast1. List of available regions: https://cloud.google.com/dialogflow/es/docs/how/region

{
  "botium": {
    "Capabilities": {
      "PROJECTNAME": "<whatever>",
      "CONTAINERMODE": "dialogflow",
      "DIALOGFLOW_PROJECT_ID": "<google project id>/locations/<dialogflow region>",
      "DIALOGFLOW_CLIENT_EMAIL": "<service credentials email>",
      "DIALOGFLOW_PRIVATE_KEY": "<service credentials private key>",
      "DIALOGFLOW_API_ENDPOINT": "<dialogflow region>-dialogflow.googleapis.com"
    }
  }
}

Open Issues and Restrictions

Account Linking is not supported (Consider using Botium Connector for Google Assistant if you want to test it)
Not all dialogflow response is supported, just
- Text,
- Image
- Quick replies
- Cards (You see cards as texts, images, and buttons)

botium-connector-dialogflow