Google Assistant

This node.js example connector uses the Google Actions SDK which allows you to make your Teneo bot available on Google Assistant and Google Home. The connector acts as middleware between the Google Assistant and Teneo. This guide will take you through the steps needed to make your bot available for testing on Google Assistant.

Google is sunsetting Conversational Actions, which allow you to create custom experiences or conversations for Google Assistant users. To ensure you have sufficient time to plan with care and support your users, the turndown is occurring on June 13, 2023.

Logo Google Assistant

You can find the source code of this connector on Github.

Prerequisites

Https

Google Assistant requires that the connector is available via https. On this page we will be using Heroku to host this connector, for which a (free) Heroku account is needed. You can however also manually install the connector on a location of your choice, see Running the connector locally.

Teneo Engine

Your bot needs to be published and you need to know the engine URL.

Google Actions CLI

You will need to install the Google Actions Command Line Interface gaction CLI.

Setup instructions

Deploy the bot connector

Click the button below to deploy the connector to Heroku:
In the 'Config Vars' section, add the following:
- TENEO_ENGINE_URL: The engine URL.
Click 'View app' and copy the URL of your Heroku app and store it somewhere, you will need it later. It will be referred to as your 'connector URL'.

If you prefer to run your bot locally, see Running the connector locally.

Running the connector locally

If you prefer to manually install this connector or run it locally so you can extend it, proceed as follows:

Download or clone the connector source code from Github.
Install dependencies by running npm install in the folder where you stored the source.
Make sure your connector is available via https. When running locally you can for example use ngrok for this: ngrok.com. The connector runs on port 3769 by default.
Create a .env file in the folder where you stored the source and add the URL of your engine. Optionally you can also specify the port number: TENEO_ENGINE_URL=<your_engine_url> PORT=3769
Start the connector with the following command: node server.js

Create a Google Assistant Project

Go to the Actions on Google Developer Console.
Click on Add Project, enter name for the project, specify language and country and click Create Project.
On the page that appears, scroll down, select 'Custom', and click 'Next'.
Select 'Conversation Component', click 'Start Building', and wait a few moments for the Action Console's dashboard to appear.
On the screen that appears, under 'Quick Setup', click 'Decide how your Action is invoked'
In 'Display Name', choose the invocation name you want to use to start a conversation with your bot. Note: Some words are not allowed in the display name, for example: 'bot', 'assistant, and 'Google'.
Select a Google Assistant Voice, and click 'Save'.

Create an Action package

In order to connect your bot to Google Assistant, you first need to create your own 'action package' locally as a JSON file. You will 'push' this action package to Google Assistant later.

Create a text file with the following content:

json

1{
2    "actions": [
3        {
4            "description": "Default Welcome Intent",
5            "name": "MAIN",
6            "intent": {
7                "name": "actions.intent.MAIN"
8            },
9            "fulfillment": {
10                "conversationName": "teneo"
11            }
12        },
13        {
14            "description": "Conversational inputs",
15            "name": "TEXT",
16            "intent": {
17                "name": "actions.intent.TEXT"
18            },
19            "fulfillment": {
20                "conversationName": "teneo"
21            }
22        }
23    ],
24    "conversations": {
25        "teneo": {
26            "name": "teneo",
27            "url": "YOUR_CONNECTOR_URL"
28        }
29    },
30    "locale": "en"
31}
32

Replace YOUR_CONNECTOR_URL with the URL of your deployed bot connector.
Save the file and call it action.json.

Alternatively you can use the Google Actions Command Line Interface to generate an action.json file by running the command gactions init

Push your action package to the Assistant Platform

Download the gactions CLI and follow the installation instructions.
Run the following command to push your action package to the Assistant Platform (replace PROJECT_ID with the id of your Google Assistant project): $ gactions update --action_package action.json --project PROJECT_ID (alternatively you can modify the 'Update action command' you copied earlier and replace 'PACKAGE_NAME' with 'action.json')
Follow the instructions in the terminal to authenticate.

You can find the PROJECT_ID in the URL of your Google Assistant Project that you created earlier. In the next example URL, the part in bold is the PROJECT_ID: https://console.actions.google.com/u/0/project/**myproject**/overview

Test your bot

You should now be able to test your bot:

Open your project on the Actions on Google Developer Console.
Click on the 'Test' tab. Then, if this is the first time you open 'Test', a 'Start Testing' button may be shown. Click it and select 'Version-Draft' as the default action.
To activate your bot, ask Google Assistant 'Talk to [your bot invocation name]'. After that, your inputs will be sent to your bot.

Engine input parameters

The connector will send the following input parameter along with the user input to the Teneo engine:

channel: The input parameter channel with value googleactions is included in each request. This allows you to add channel specfic optimizations to your bot.

Engine output parameters

The connector will check for the following output parameters in an output:

gaOutputType: By default the connector will open the microphone after each answer that was received from Teneo. If the output parameter gaOutputType with the value close exists, the conversation will be ended.
googleactions: To send rich responses, this connector looks for an output parameter googleactions in the engine response. The value of that parameter is assumed to contain the rich response JSON as defined by Google.

If we look at Google's specification of a basic card, the value of the googleactions output parameter to attach an image would look like this:

json

1{
2    "basicCard": {
3        "image": {
4            "url": "https://url.to/an/image.png",
5            "accessibilityText": "Alternate text"
6        },
7        "imageDisplayOptions": "CROPPED"
8    }
9}
10

For more details on how to populate output parameters in Teneo, please see: How to populate output parameters in the Build your bot section.