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


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 intents, 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 webhook 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, context names are prefixed with information about session-id etc.

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


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

About this website

BotFlo1 was created by Aravind Mohanoor as a website which provided training and tools for non-programmers who were2 building Dialogflow chatbots.

This website has now expanded into other topics in Natural Language Processing, including the recent Large Language Models (GPT etc.) with a special focus on helping non-programmers identify and use the right tool for their specific NLP task.

1 BotFlo was previously called MiningBusinessData. That is why you see that name in many videos

2 And still are building Dialogflow chatbots. Dialogflow ES first evolved into Dialogflow CX, and Dialogflow CX itself evolved to add Generative AI features in mid-2023

  • Now, Dialogflow is shutdown V1API and moving to V2API, I had to change my API request to detect particular intent to V2API from V1API..Currently, I am getting the intent like this..https://api.dialogflow.com/v1/detectIntent?v=20170712&detectIntent=” + “Who are you?”..Could you please guide me on this please??I am referring dialogflow migration documents, But documents are not convinient enough for my knowledge..Please guide me to call intent in V2API..

    • Make sure you read this article first.

      I think just like in Android, you cannot expose the client secret on the device, and so creating a middleware layer to talk to your agent may be your best bet.

  • Great article!
    Do you know if Dialogflow will dismiss v1 in the near future? I wouldn’t like my chatbots to stop working.
    I’m looking forwards to the API v2 course.

    • The Dialogflow team have announced that they will support v1 for a year in documentation updated in Feb 2018. Since v2 requires a pretty big change in even a reasonably complex bot, and Dialogflow folks have already said v1 will not get support for new features, I think it is best for folks to start thinking about the migration soon.