Home / DialogFlow / REST API / Dialogflow: Is it time to switch to v2 API?
DialogFlow | 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)

Feedback

Have you run into any issues with migration? I would love to know your thoughts in the comments.

REST API v2 Course

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

Related 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.