Botkit Middleware Dialogflow
A middleware plugin for Botkit that allows developers to integrate with Google Dialogflow, leveraging the power of both to build chatbot applications on Node for social platforms like Slack, Facebook and Twilio.
Dialogflow's Natural Language Processing (NLP) platform transforms real-world user input into structured intents and entities, and can optionally trigger actions and fulfillment (webhooks). Configuration and training are done in the convenient and powerful Dialogflow Console, with the results being immediately available to your bot.
- Migrating from earlier versions
- Quick Start
- Middleware functions
- Language Support
- Legacy V1 API
- Change Log
- Botkit v0.7.x
- Node 8+
npm install botkit-middleware-dialogflow
Migrating from earlier versions
Dialogflow has two versions of their API. V2 is the standard, and should be the default for new agents.
However, if you need to migrate from Dialogflow API V1, or are upgrading from earlier versions of
botkit-middleware-dialogflow, consider the following factors:
- some Botkit
messageproperties have changed.
actionproperty is new
nlpResponseobject structure has changed significantly.
- V2 users must provide a JSON keyfile instead of an API key for DialogFlow authentication
- options parameter
minimum_confidencehas been renamed
minimumConfidenceto match the predominant style.
botkit-middleware-dialogflow continues to support both versions of the API. Instructions for legacy V1 are below.
1. Setup an Agent in Dialogflow
Agents as NLU (Natural Language Understanding) modules. They transform natural user requests into structured, actionable data.
- In the Dialogflow Console, create an agent
- Choose or create a Google Cloud Platform (GCP) Project.
- Dialogflow will automatically setup a
Default Welcome Intent, which you can try from the test console.
2. Create a service account
In order for your Bot to access your Dialogflow Agent, you will need to create a
service account. A Service account is an identity that allows your bot to access the Dialogflow services on your behalf. Once configured, you can download the private key for your service account as a JSON file.
- Open the GCP Cloud Console, and select the project which contains your agent.
- From the
IAM & admin,
Dialogflow Integrations(created by default by Dialogflow), or create your own.
create key, select
JSONand download the file.
3. Add the middleware to your Bot
Using Slack (as an example), wire up your Bot to listen for the
Default Welcome Intent, and then pass along the reply that Dialogflow recommends in
const Botkit = ;const dialogflowMiddleware =keyFilename: './mybot-service-key.json' // service account private key file from Google Cloud Console;const slackController = Botkit;const slackBot = slackController;slackControllermiddlewarereceive;slackBot;slackController;
4. Try it out!
Botkit supports middleware integration into core bot processes in a few useful places, described here.
Each time the chat platform (eg. Slack, Facebook etc) emits a message to Botkit,
receive middleware to process that message and optionally modify it, before passing it back to Botkit and on down the chain.
First, create an instance of the middleware:
const dialogflowMiddleware = options;
keyFilename is the only property of
options that needs to be set. See options section for full list.
Next, tell the
controller that you want to use the middleware:
Not every message should be sent to DialogFlow, such as
user_typing indicators. To avoid these uneccessary calls,
botkit-middleware-dialogflow allows you to specify which message types to ignore, using the
Since the middleware is part of the message pipeline, Botkit has already ingested, normalized and categorized the message by the time we apply this filter. Keep this in mind when choosing which types to ignore.
Assuming the message has passed the
ignoreType filter, it's sent off to the Dialogflow API for processing. The response is parsed and applied to the
message object itself.
Specifically, here are the new
message properties available after processing:
message.intentintents recognized by Dialogflow (eg. saying 'hi' might trigger the
message.entitiesentities found as defined in Dialogflow (eg. dates, places, etc)
message.actionactions and parameters triggered by the intent
message.fulfillmentfulfillment triggered by the intent, such as webhooks or text responses.
message.confidenceintent detection confidence. Values range from 0.0 (completely uncertain) to 1.0 (completely certain).
message.nlpResponsethe raw Dialogflow API response.
Here is a diff of a message object, before and after middleware processing.
To make your bot listen for the intent name configured in Dialogflow, we need to change the way Botkit "hears" triggers, by passing our middleware into the
hears() event handler.
For example, using our
dialogflowMiddleware object defined above:
Notice we are listening for
hello-intent - that's the name we gave the intent in the Dialogflow Console.
Patterns used to match the intent name can be provided as comma seperated strings, regex, or an array of strings and regex.
'hello-intent'// matches hello-intent, HELLO-INTENT case insensitive
['hello-intent', /^HELLO.*/i]// matches hello-intent, hello, or HELLotherejimmy
'hello-intent,greeting-intent'// matches hello-intent or greeting-intent'
Patterns are compared with the
message.intent property after the
receives() function has processed it.
When an intent is triggered, a Dialogflow agent can be configured to take an action. The name of the action is captured in the
message.action property, after procesing by the middleware.
You can setup a
hears() event handler to trigger on
message.action as well.
The patterns format is the same as
When creating the middleware object, pass an options object with the following parameters.
|ignoreType||No||'self_message'||Skip Dialogflow processing if the
|minimumConfidence||No||0.0||Dialogflow returns a confidence (in the range 0.0 to 1.0) for each matching intent. This value is the cutoff - the
|sessionIdProps||No||['user', 'channel']||Session ID's help Dialogflow preserve context across multiple calls. By default, this session ID is an MD5 hash of the
|version||No||v2||Version of the dialogflow API to use. Your agent needs to use the same setting for your agent in the DialogFlow console.|
|token||Yes (v1 only)||Client access token, from the Dialogflow Console. Only required with version v1.|
|keyFilename||Yes (v2 only)||Path to the a .json key downloaded from the Google Developers Console. Can be relative to where the process is being run from. Alternatively, set DIALOGFLOW_CLIENT_EMAIL and DIALOGFLOW_PRIVATE_KEY in the environment using values found in the keyFile.|
||The Google project ID your Dialogflow V2 agent belongs to. You can find it in the agent settings. If using a keyFile, the middleware will find it automatically. May also be set using DIALOGFLOW_PROJECT_ID in the environment.|
v2 users can optionally provide a path to a .pem or .p12
keyFilename, in which case you must specify an
projectIdparameter as well.
Dialogflow supports multi-language agents. If the
message object has a
lang value set,
the middleware will send it to Dialogflow and the response will be in that language, if the agent supports it.
By default, Botkit
message objects do not have a langauge specified, so Dialogflow defaults to
For example, to invoke the Dialogflow agent in French, set your
message as such:
messagelang = 'fr';
To enable debug logging, specify
dialogflow-middleware in the
DEBUG environment variable, like this:
DEBUG=dialogflow-middleware node your_awesome_bot.js
By default, objects are only logged to a depth of 2. To recurse indefinitely, set
null, like this:
DEBUG=dialogflow-middleware DEBUG_DEPTH=null node your_awesome_bot.js
Legacy V1 API
To use the legacy V1 version of the Dialogflow API:
- In the Dialogflow console:
- In the agent settings, select
- Note the
Client access token.
- In the agent settings, select
- Set options for the middleware:
Client access tokenfrom the Dialogflow console.
versionshould be set to
botkit-middleware-dialogflowto use the legacy API.
- minimumConfidence now defaults to 0.0
- Dialogflow credentials can be set using environment variables
- drop support for Node 7
- Fix projectId not detected when passed in config
- refactor to support Dialogflow API V2
- readme updates
- defaults and examples now use Dialogflow API V2
- sessionId sent to DF based on user and channel properties of message
- allow customization of sessionId to use different properties as desired
- support for sending queries to Dialogflow in different languages, specified by lang prop on message
- add TOC to README
- fix #9 add support for ignoreType to avoid unneccessary API calls to DF
- more debugging tips in README
- restore images in readme
- fix #5 add full support for regex and strings for intents and actions
- change slack example env variable to improve clarity
- add tests for existing functionality
- update criteria for skipping middleware automatically
- remove skip_bot option
- travis and changelog added
- readme updates
- updated examples
- filter out self_message type from slack
- ignore editor files
- migrate to eslint and apply formatter to comply with .eslintrc rules
- add debug logging
- rebrand as dialogflow
pre-fork as botkit-middleware-apiai
- initial release
If you would like to help make
botkit-middleware-dialogflow better, please open an issue in Github, or send me a pull request.
Feedback, suggestions and PRs are welcome.
Also thanks to @ehrhart for patches supporting V2.
This library is licensed under the MIT license. Full text is available in LICENSE.