Dialogflow API v2 versus v1

Dialogflow recently announced that version 2 of their API is generally available.

I have been asked by some readers as to what this means for their integrations, and I have summarized it in this article.

How it works

v2 API is quite different from v1 API even in the way the basic system works.

For v1, you had two access tokens – called client access token and developer access token.

These access tokens had different levels of permission – the client access token was less powerful and meant mostly for read-only tasks, while the developer access token was a lot more powerful and meant for edits/updates/deletes.

To see a comparison between the two types of access tokens, you can read this article.

All you had to do was to use these two tokens in your API calls and it was sufficient to interact with the v1 API. This did raise some issues, and I point out one of them in my article about not exposing the client access token in your Javascript.

With v2, the system you use to access the API has gone through a complete overhaul. It adheres to Google’s OAuth2 conventions – so you now have to understand (to some extent) a larger vocabulary – roles/permissions in Google Cloud administered via IAM (Identity and Access Management), service accounts (which can execute API calls on behalf of users), client secret JSON files and such. For example, this is a brief overview of how you would use v2 API:

• create a new service account from Google’s cloud console
• download a client secret JSON file
• use the appropriate client libraries (based on your programming language) so it can use the client secret and make calls to the API
• use the different API methods exposed in the client library to build out your integration

Comparison

So how does v2 compare with v1? (Note: some of these are my personal views)

v1 is simpler to use

This is quite clear. Because of v1’s simplicity, for example, it was possible to create WordPress plugins which would use the client access token right inside the Javascript to create pretty sophisticated website chatbots. The simplicity of v1 certainly helped grow Dialogflow’s ecosystem.

v2 is more secure

As I mentioned before, the ease and simplicity of v1 also meant sometimes folks used it a little more casually than they should have.

v2 is more secure and follows industry best practices and conventions (OAuth2).

Read the top voted answer on this StackOverflow thread if you want to read a funny explanation of OAuth.

v2 supports more features

For example, there is no way to specify an intent as a followup intent of another in the v1 API, while it is possible in API v2.

Only v2 will get newer features

Similar to how you cannot use v1 API for creating followup intentsBoth Dialogflow ES and Dialogflow CX have the concept of int... More, in the future, you can expect that the v2 API will exclusively get access to new features while v1 API will not be updated to reflect such new features. Dialogflow team calls this out quite explicitly.

v2 makes it more important to have a coder on your team

Sure, you could go and figure out Google’s IAM, and read all about the roles and permissions in Google Cloud, and then figure out Google’s API discovery tools, and then also understand how to use the HTTP API Annotation syntax (if you want to write all the code yourself). And you could use one of the client libraries and get started a bit more quickly but still end up learning about all the previous stuff if you need to code a corner case not covered in the client library.

Or you can add a coder to your team and have them figure out this stuff. As I have mentioned previously, while Dialogflow looks from the outside like a no-code tool, at the moment you do need to get help from a programmer to build reasonably useful chatbots.

v2 will make it more important to understand OAuth2 conventions

While the client libraries might abstract away the details of OAuth2 implementation, you still need to get a basic understanding of what is going on under the hood to be able to use the client library properly.

Using v2 will require you to learn how Google cloud services work

Since the client libraries are also quite closely tied to the Google Cloud, you would also need to get a fair understanding of Google cloud services. On the plus side, learning about the Google ecosystem will benefit you when you start writing your webhookYou can use webhooks to add custom business logic in both Di... More code.

Your API v1 Webhook code must be changed

One of the things which has been changed is the format of the JSON object which is sent to your webhook code.

This is what the v1 JSON object sent to the webhook looked like:

Notice that the root “field” (which contains most of the important and relevant information) is “result”.

This is how it has changed in v2:

As you can see the root field is now called “queryResult”.

There are also a few more important changes. For example, contextContexts are used in Dialogflow ES to manage the state of th... More names are prefixed with information about session-id etc.

So your webhook code needs to be modified to use the updated JSON object.

Summary

Here is how I would approach the task of learning how to use the v2 API if I were starting today:

1 Spend some time playing around in Google’s OAuth2 playground

2 Spend some time learning about roles/permissions in Google cloud and what service accounts do (this is more important than you think, plus as an added bonus learning about this material can help you with other Google APIs)

3 Spend some time working with the client libraries

Note: This is my old website and is in maintenance mode. I am publishing new articles only on my new website. 

If you are not sure where to start on my new website, I recommend the following article:

Is Dialogflow still relevant in the era of Large Language Models?