How to build a Google Maps plugin for Cognigy.AI’s Webchat

Context is key for a delightful conversational experience, because utterances often can’t be understood in isolation, they can only be understood in context. Therefore, how cool would it be to use location-based services and display maps? With Cognigy.AI this works like a charm, thanks to its

• Custom Integration Framework, and
• extensible Webchat architecture.

In this tutorial we will learn how to use a webchat plugin to show an exact location on a map using Google Maps and how to build a Custom Module to invoke the plugin in a user-friendly way.

Locations and maps: Enrich a conversation with context and multimodal elements to improve the User Experience.

Building a Webchat Plugin to display Google Maps

We take the Google Maps React component as a starting point and turn it into a Webchat Plugin for the conversational AI platform Cognigy.AI according to the instructions here:

1. Setting up the environment

2. Writing the code

3. Using the Plugin

Setting up the environment

1. Create a new project plugin and initialize it with npm init

2. Also, install react, @google/maps, google-map-react, react-dom by running npm i “component” successively

3. The installation has changed your package.js-file. Now, add a build job in the scripts field:

“build”: “parcel build — out-file webchat-plugin.js ./src/index.jsx”

4. Create a folder named src in which you create an index.jsx file, which we will fill in the next steps.

Writing the code

All the logic of a Webchat Plugin goes into the index.jsx file as a react based “Message Component”.

1. Create a React Component that will be used to render a message. Via its props, it will get a message property representing the content of the message we want to render. Inside that message object, we have a <div> with a size containing a GoogleMapReact component.

2. Now that we have our Message Component, it’s time to use it in a plugin definition. A Message Plugin definition is an object that must contain a match and a component value. The match value is used to decide for which messages this plugin should be used, and the component value tells the webchat what Message Component to use with this plugin. Setting match to ‘google-maps’ means that this plugin will match if a message has data that is set up like this:

{
 "_plugin":{
  "type":"google-maps"
 }
}

3. Finally, register the Plugin. In order to cause the plugin to be recognized by the webchat, it needs to be put at a specific location in the window object. At that location, we have a list of webchat plugins where we want to append out plugin. Because our plugin might be registered first, it may be that the list does not exist yet, so we must make sure to create it if it does not exist yet.

Using the Plugin

Now that we have our complete plugin code ready, we can go on and build it, load it into the inbuilt Cognigy.AI webchat and use it.

1. To create a package of the Webchat Plugin enter npm run build in the command line within the plugin folder. It should create a webchat-plugin.js file.

2. Upload that file to a web server the chatbot can access (for example Amazon S3).

3. Now add the Plugin URL in Webchat Plugins section at the bottom of your Webchat configuration by clicking +.

4. Now in a Cognigy Flow, create a Say Node that calls the plugin[PH1] by filling the data part as follows:

If you want to use the plugin on your live website, you have to include the plugin into your website source as explained here: https://docs.cognigy.com/docs/working-with-webchat-plugins-in-cognigy-ui

Building a Custom Module to retrieve a location using Google’s Geocoding API

Whilst we can trigger plugins from a Say Node, it would be more convenient to give business users a graphical UI to configure the plugin. This we can achieve with a Custom Module.

To use the Webchat Plugin built in the previous step, you need the longitude and latitude. If you don’t have those coordinates, you can use a geocoding API. Thus, we build a Custom Module for Cognigy.AI’s Custom Integration Framework. This makes accessing the Google’s Geocoding API easy. You only need to send it the desired address and get the coordinates in return. Those can then be used for displaying a map inside the conversation. Follow the steps below to create a Custom Module for this purpose:

1. Setting up the environment

2. Writing the code

3. Using the Custom Module

Setting up the environment

1. Create a new project called Custom Module and initialize it with npm init

2. Also install request & request-promise by running npm I “component” successively

3. Customize the package.json document so that the main line looks like this:

“main”: “src/module.js”,

4. Always create a README.md file

5. Create a folder src in which you create a module.js file

Writing the code

All the logic of a Custom Module goes into the module.js file.

1. Use the require function to resolve the request-promise module in the Node search path

const request = require(‘request-promise’);

2. Define the input fields that should be available in your custom module

3. Now we define an asynchronous function showGoogleMaps with two parameters. Make sure all parameters have the correct content. When we receive an address to search for, the request will be sent to Google Maps Geocoding and we will get the appropriate longitude and latitude values. This requires a valid API key.

4. Generate in the function a message that can be interpreted by the plugin. And then return a Cognigy.AI object.

Using the Custom Module

1. Zip the root of the module and the / build folder

2. Upload the zipped module into your Cognigy.AI installation through the Cognigy Integration Framework Manager.

Now we have all the components together and can use the Google Maps Plugin with a Webchat:

1. If you are using the Cognigy.AI Webchat, enter the URL of your plugin there.

2. Create a Cognigy Secret in your Cognigy.AI-Project for accessing the Google API. The secret key needs to be named api_key and the value must contain your Google Maps API Key.

3. Create a flow using your Custom Module Node.

4. Add the Node and fill in all the necessary fields of the module to display the Google Map. The Secret field requires a Cognigy Secret with a valid Google Maps API Key (see step 2).

What’s next?

Want to take the Custom Module and Webchat Plugin for a spin? Check out our Module GitHub Repo https://github.com/Cognigy/CustomModules and our example Webchat Plugins https://github.com/Cognigy/WebchatPlugins/blob/master/docs/examples.md. Need more technical information? Have a look at our docs: https://docs.cognigy.com/docs. Ready to give it a go? Contact your Cognigy.AI sales rep or request a demo: https://hello.cognigy.com/cognigy-demo-request!