Home / DialogFlow ES / Dialogflow: Is it time to switch to v2 API?
DialogFlow ES | REST API

Dialogflow: Is it time to switch to v2 API?

I have been asked this question by a few folks recently. While it generally depends on the “stage” of your Dialogflow project, I think the answer is tending towards Yes already.

What stage is your project on?

First, what stage are you in your project?

Later stage project

If you are later stage in your Dialogflow project, the odds are you already know all the pros and cons of switching to v2 API, plus you are already well prepared since you will incur the heaviest cost. So I don’t think you need any suggestions from me (and odds are, if the project is already somewhat mature, you are probably not the intended audience for this blog).

Recently started

Here, the cost of migration is not trivial, but not very huge either. I think you should migrate as soon as possible.

Yet to begin

Well, even though the vast majority of tutorials you find on the web deal with API v1, I think that this gap will be filled quite quickly and in any case, a lot of your learning will carry over even when you move to v2. So I would recommend starting your project with v2 (which is actually the default choice in Dialogflow right now).

What needs to be changed?

I think there is no surprise that external API integrations (for example, the website chatbot I have built, which still runs on v1 API) need to be updated to use API v2.

But what is a bit more surprising is that your existing v1 webhooks will also need to be modified if you are going to move to API v2.

Note: many folks reading the tutorials on my site don’t seem to be aware that Dialogflow webhook code intended for v1 API breaks when used with v2 API. Plus, the fact that Dialogflow has now made v2 API as the default for a new project means more people will be running into this issue until I update the tutorials to indicate whether they use v1 or v2 API.

An interesting update is that some of the system entities return different types of objects in the JSON. A good example is the date-period system entity.

v1 API:

v2 API:

I was interested in finding out whether this would affect the output sent to the user (meaning this would affect your chatbot if there was some process downstream relying on the format and parsing the dates out).

For example, imagine an intent where you echo back the value of a date period you receive from the user:

Here is the Simulator response for v1:

And here is the response for v2:

You can see that while the date-period value that Dialogflow extracts comes back in a different format in v2, the actual text response produced by using $date-period in the Text response section is preserved.

Overall, as you are migrating your agent, I think the documentation provided by Dialogflow is a pretty good reference (and leave a comment below if you would like me to clarify or expand upon anything in the docs).

Why change?

Here are some reasons to change:

  • v1 will be sunsetted at some not-so-distant point in the future, so why keep developing against it?
  • the new features introduced to Dialogflow will only be accessible via v2
  • the API for v2 is better as it already exposes more functionality (e.g. export ZIP)
  • v2 is also more secure as it uses OAuth
  • and it is likely more of the non-Google articles/resources you find on the web will start reflecting v2 API rather than v1 (I have certainly made it a priority for my website)

REST API v2 Course

Nov 2018 update: You might also be interested in my course on REST API v2.

<— End of article —>

This website contains affiliate links. See the disclosure page for more details. 
"The magic key I needed as a non-programmer"

The custom payload generator was the magic key I needed (as a non-programmer) to build a good demo with rich responses in DialogFlow Messenger. I've only used it for 30 minutes and am thrilled. I've spent hours trying to figure out some of the intricacies of DialogFlow on my own. Over and over, I kept coming back to Aravind's tutorials available on-line. I trust the other functionalities I learn to use in the app will save me additional time and heartburn.

- Kathleen R
Cofounder, gathrHealth
"Much clearer than the official documentation to be honest"

Thanks a lot for the advice (of buying and following your videos)! They helped a lot indeed. Everything is very clear when you explain, much clearer than the official documentation to be honest 🙂

Neuraz T
Review for Learn Dialogflow CX
"I will strongly recommend this course because even I can learn how to design chatbot (no programming background)"

I think Aravind really did a great job to introduce dialogflow to people like me, without programming background. He organizes his course in very clear manner since I have been a college professor for 20 years. It is very easy for me to recognize how great Aravind’s course is! Very use-friend and very easy to follow. He doesn’t have any strong accent when he gives the lectures. It is so easy for me to understand. Really appreciate it.

Yes, I will strongly recommend this course because even I can learn how to design chatbot (no programming background) after studying Avarind’s course, you definitely can!

Ann Cai
Review for Learn Dialogflow ES

Similar Posts

  • Hey Aravind, Small doubt – My production action was v1 so I have made the changes and switched to v2 and changed my webhook endpoint, so should I resubmit my action to google to apply the changes in production.

    • All the projects I created were built with v2.

      Having said that, I think you should resubmit. It will make sure you don’t run into any surprises in the future.

    • I am not actually affiliated with Dialogflow/Google, so I don’t know the answer. I have also seen that the Dialogflow team has generally avoided replying to this question on the forums. So as the old saying goes: “Prepare for the worst, hope for the best”. 🙂

  • Great article, Aravind! Any idea how to integrate V2 in with React or Vue? The dialogflow-javascript-client doesn’t seem to exist yet for V2.

    • To the best of my knowledge, the OAuth model in v2 means that you cannot have pure client side JavaScript talking to Dialogflow via API. You will end up exposing the client secret JSON file. You need to have a corresponding “relay server” which runs a server side programming language to be able to talk to Dialogflow via v2 API.