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