Dialogflow Integration

Introduction

The purpose of this documentation is to set up an integration deployment to connect your existing Dialogflow agent to various third party chat service platforms.

If you do not have an existing Dialogflow agent, you can set one up by reading the documentation here.

Although it is possible to set up this integration deployment on any hosting platform, these instructions will use Google's Cloud Run.

Initial Setup

Setting up gcloud CLI

The deployment process for GCP Cloud Run via this README utilizes gcloud CLI commands. Follow the steps below to set up gcloud CLI locally for this deployment.

On the gcloud CLI documentation page, select your OS and follow the instructions for the installation.
Run gcloud config get-value project to check the GCP Project configured.
Go into the Dialogflow agent’s settings and check the Project ID associated with the agent. The GCP Project configured in the gcloud CLI should match the agent’s Project ID.
If the project IDs do not match, run gcloud config set project PROJECT-ID, replacing PROJECT-ID with the Project ID from step 3.

Service Account Setup (GCP)

For the integration to function properly, it is necessary to create a Service Account in your agent’s GCP Project. See this page of the documentation for more details.

Follow the steps below to create a Service Account and set up the integration.

Go into the Dialogflow agent’s settings and click on the Project ID link to open its associated GCP Project.
Click on the navigation menu in the GCP console, hover over "IAM & admin", and click "Service accounts".
Click on "+ CREATE SERVICE ACCOUNT", fill in the details, and give it the "Dialogflow API Client" role.

If deploying this integration outside of GCP, you may authenticate using a key file. Deploying on Cloud Run or Cloud Functions obviates this process.

Click on "+ Create Key" and download the resulting JSON key file.
Save the JSON key file in the desired platform subdirectory.
Set the GOOGLE_APPLICATION_CREDENTIALS environmental variable on the deployment environment to the absolute path of Service Account JSON key file. See this guide for details.

Deploying the Integration

Setup

Go into the Dialogflow agent’s settings and click on the Project ID link to open its associated GCP Project.
Click on the navigation menu in the GCP console and click "Billing". Set up and enable billing for the project.
Enable Cloud Build and Cloud Run API for the project here.
Clone this git repository onto your local machine or development environment: git clone [repository url]
Open the root directory of the repository on your local machine or development environment.

Dockerfile and Creating the Build

Open the Dockerfile in the root directory of the repository, and change YOUR_INTEGRATION in the following line to the name of the desired platform subdirectory.

   # Set this environmental variable to the integration you want to use
   ENV INTEGRATION=YOUR_INTEGRATION

If you have not done so already, copy your Service Account JSON key file to the desired platform subdirectory.

Platform-specific Instructions

The integration requires platform credentials from the intended platform to function properly.

Follow the steps in the README file in the relevant platform subdirectory to obtain the credentials and setup the server.js file to deploy and start the integration:

Post-deployment

Shutting Down an Integration

In order to shut down an integration set up via the steps in this README, only deleting the Cloud Run service is required.

In your local terminal, run the following command and select the previously chosen target platform to list active deployments:

gcloud beta run services list

Then run the following command, replacing SERVICE-NAME with the name of the service you want to shut down, and select the same settings chosen when deploying in order to shut down the deployment.

gcloud beta run services delete SERVICE-NAME

If following the instructions closely, SERVICE-NAME should be in the format of dialogflow-PLATFORM

Multiple Integrations

To set up multiple integration deployments simultaneously, repeat all of the instructions for each deployment. While it is possible to make changes to the existing deployment repository and re-deploy it under a different name, it would make it difficult to retroactively make changes to previous deployments.

Changing Integration Behavior

The behavior of an integration can be customized via the addition of your own developer code or by editing the server.js file in the platform subdirectory.

After making changes, redeploy the deployment by re-running the commands as specified in the "Deploy the Integration Using Cloud Run" section of the platform-specific integration READMEs.