Migrating to the Dialogflow API v2

On April 17, 2018 version 2 of the Dialogflow API was made generally available. It marked the end of a beta phase that started back in November 2017.

Our API V2 now serves as the default API for all new Dialogflow agents, and all new feature upgrades will only be released for API V2.

I remember reading the above in the announcement blog post, telling myself to upgrade my “I Owe You” Google Assistant bot as a way to learn about the new API. Last weekend, I did exactly that and this blog post explains my approach.

Target Audience

The main focus of this post is on the migration from an existing Dialogflow project that uses v1 of the API to the new API v2.

If you’re new to Dialogflow, I recommend to get started with https://dialogflow.com/docs/getting-started/basics, it contains the necessary steps to create a Dialogflow project. You won’t need to read the rest of this article since v2 is now the default API version.

API V1

I originally started with an “Actions on Google” project, which means my project directory structure looked like this:

.firebasercfunctions├── index.js└── package.json

The index.js file contained the fulfillment logic for my bot, similar to the following:

// index.jsconst App = require("actions-on-google").DialogflowApp;

const welcome = app => {app.ask('Welcome! How can I help you today?');}

exports.iOweYou = functions.https.onRequest((request, response) => {const app = new App({ request, response });

// Create the action maplet actionMap = new Map();actionMap.set('input.welcome', welcome);// ... custom actions added here

app.handleRequest(actionMap);});

As a visualization, the API v1 setup looked like this:

Migration Guide

If you’re in a similar situation as me and want to upgrade to v2, I highly recommend reading the official migration guide at https://dialogflow.com/docs/reference/v1-v2-migration-guide.

My bot doesn’t have an integration to Slack, Skype, or any of the other integrations Dialogflow supports. All I had to migrate was the fulfillment endpoint. There is a chapter in the migration guide specifically for this use case and it lists the necessary steps. If your bot has an integration enabled, please refer to the official migration guide for details.

In summary, migrating a fulfillment endpoint requires you to create a new agent, import the v1 agent (so you don’t have to create intents, entities, etc. from scratch), enable v2 on the new agent, upgrade your fulfillment code, test it all, release to production.

In the v2 test agent, the fulfillment webhook URL needs to point to a new endpoint, the one we are going to migrate to v2. Open Dialogflow, select your v2 test agent and click on “Fulfillment” in the navigation. In the webhook’s URL field, append V2 to the already populated URL.

By now, we have a v2 agent we can use for testing that points to a v2 fulfillment endpoint. What’s missing? The actual v2 of the fulfillment endpoint. Let’s start with a diagram:

The main index.js file exports two functions. One is the original iOweYou that serves production traffic and the other one is a iOweYouV2 version that is used by the new test agent we upgraded to the Dialogflow API v2.

To keep things organized, I suggest you extract the v1 code into a separate index-v1.js file and create an index-v2.js file for the new code.

Dialogflow Fulfillment Library Beta

As part of that migration, I decided to take advantage of this new Node.js fulfillment library. You can read more about it and see examples at https://github.com/dialogflow/dialogflow-fulfillment-nodejs.

While the “I Owe You” bot currently only supports Google Assistant, using the fulfillment library is a great starting point to enable integrations to 8 chat and voice platforms in total down the road.

API V2

Once index-v2.js is ready and well tested, it’s time to migrate the production traffic to the new API. Given the separation of v1 and v2 fulfillment code in individual files, migrating the production traffic to v2 is simple. The following diagram outlines what’s required:

The steps include:

1. Make sure the exported iOweYou property loads the -v2 index file.
2. In Dialogflow, open your production agent and switch to the API v2.
3. At this point, the bot in production runs on the Dialogflow API v2. I suggest you run it like that for a while, monitor the logs and if anything goes wrong, revert step 1 and 2 above to roll back to the v1 implementation.
4. Once you’re satisfied and see no errors or drop offs in your conversations, it’s safe to clean up the code and remove the index-v1.js file. At this point you can also remove your test agent in Dialogflow.

Simple, isn’t it?

If you have any questions or suggestions, please leave a comment and I’ll get back to you.