Google's Dialogflow APIs

Last modified 27 days ago / Edit on Github

Google's documentation is like an ocean. It's not easy to find a right one to start. This note contains only basic things that I've already worked with. Trying your own hand at Google's APIs will help you understand more.

πŸ‘‰ Github: dinhanhthi/google-api-playground (private).
πŸ‘‰ Note: Google's OAuth2 APIs

Official documentation

Click to show
  1. APIs & references -- the root of all things.

    1. Node.js client library -- wanna use in a backend?
      1. Dialogflow SDK Client Reference
      2. googleapis/nodejs-dialogflow -- Github repo.
        1. Samples -- wanna run these? Step to this section.
    2. REST APIs -- wanna use GET, POST,...?
  2. Service endpoint.

    πŸ’‘ Tip: us-dialogflow.googleapis.com and dialogflow.googleapis.com are the same, so you can use <location>-dialogflow.googleapis.com in your codes.

  3. Available regions (used in locations).

    πŸ’‘ Tip: <region>-dialogflow.googleapis.com = endpoint.

  4. google/google-api-javascript-client -- aka gapi. Github repo.

  5. Google APIs Explorer.

  6. OAuth 2.0 Playground.

  7. Understand roles -- If you decide to create a service account, you will need to assign a role to some users/emails. Each role has different rights to use your data.

Wanna run the Node.js samples?

πŸ‘‰ Link of all samples on github.

The old version uses dialogflow and @type/dialogflow. The new version uses only one @google-cloud/dialogflow!

Step by step
  1. Create a folder, eg. /home/thi/df-samples/

  2. If you come from Dialogflow Console > choose an agent > click on the gear next to the its name > Click on "Project ID" to open Google Cloud Platform Console.

  3. If you come from GCP Console, it's the same.

  4. Follow these steps to generate a JSON key (you'll download a JSON file). Store your JSON file in df-samples/credential.json. Note down the project_id, we will use it later, eg. project_abc.

  5. Run each time you wanna test export GOOGLE_APPLICATION_CREDENTIALS="/home/thi/df-samples/credential.json" OR save this line to /home/thi/.bashrc or /home/thi/.zshrc (if you use ZSH) and then refresh the current terminal (with this method, you don't need to run again previous line).

    Alternative: You don't have to use system variable GOOGLE_APPLICATION_CREDENTIALS if you don't want. In credential.json, copy private_key and client_email and then use them as,

    const client = new AgentsClient({
    credentials: { private_key, client_email }
    });
  6. Go to /df-samples/ and run npm i @google-cloud/dialogflow.

  7. Try this quickstart.js.

  8. On terminal, run

    node quickstart.js project_abc
  9. Read carefully the content of each file in samples, you have to put the corresponding inputs for the sample to work!

Try something outside "samples"?

In case you wanna try something outside the files given in samples. Check this SDK. Suppose we wanna try this one -- AgentsClient.searchAgents()

  1. Make the same things in "Step by step". At step 7, create search-agents.js with the same content as samples/set-agent.js. We are going to change this file.
  2. Read the reference, change the input. Here is an example,
Different locations?

The example in "Try something outside..." gives us an example of using different regions. Below are some remarks:

  1. On DF console, you can create some agents in a different regions, default is global (or us).

  2. On the Google's documentations, they don't mention about the usage of location. If they say parent = "projects/-", we shoud use parent = "projects/-" + "/locations/" + location where location can be one of "Region ID".

  3. Change also the endpoint, option apiEndpoint in AgentsClient's constructor, for example.

    const client = new AgentsClient({
    apiEndpoint: location + "-dialogflow.googleapis.com",
    });

On SDK documentation, they don't mention about the location in the parent property. For example, they say "parent can be projects/<Project ID or '-'>", but you can add the location information inside it like that

const parent = (location) => "projects/-" + "/locations/" + location; 

Wanna try gapi (JS client)?

Google has announced that they will be discontinuing the Google Sign-In JavaScript Platform Library for web. You will have to switch to using Google Identity Services (or Sign In With Google or gsi). The old service will be completely discontinued on March 31, 2023.

<!-- OLD -->
<script src="https://apis.google.com/js/platform.js" async defer></script>

<!-- NEW -->
<script src="https://accounts.google.com/gsi/client" async defer></script>

What's this gapi? You can use it completely inside an HTML file without using any backend.

πŸ‘‰ List of samples.
πŸ‘‰ You have to use REST API in this case.

πŸ’‘ Tip: If you are using VSCode, you can install the Live Server extension to quickly create a server (port 5500 by default). Just click the button at the bottom right of the file and a website will appear.

Step by step
  1. For setting up, follow these steps.
  2. After that, you should obtain an API_KEY and an CLIENT_ID.
  3. First, try this sample.
  4. Using something like Live Server and open authSample.html.
  5. Make a test.
  • Make sure you create the "OAuth consent screen" before you create "OAuth 2.0 Client IDs". The "consent screen" is the popup window that contains all the information about the scopes your app will ask users for permission.
  • Make sure you add http://localhost:5500 (which is created in step 4) to "Authorized JavaScript origins" and "Authorized redirect URIs". You may have to wait a few "ten minutes" for everything to work. Without this step, you may encounter the error mismatch_uri.

The corresponding between REST API and Node.js clients

πŸ‘‰ REST API.
πŸ‘‰ Node.js SDK.

The corresponding between references

projects.agent.search

projects.agent.sessions.detectIntent

Sometimes, the location infotmation is mentionned in the REST API but not in the SDK. For example, load the list of agents w.r.t. some location,

Using REST API in Node.js

Remark: With keys generated from a service account (stored in JSON), we can only get 1 agent for methods like projects.agent.search although it says that we can get a list of agents. In this case, try to get access token via OAuth 2.0. With this, we can access to all projects instead of only 1 (which is used to generate the json file).

Dialogflow REST APIs with Postman

πŸ‘‰ Check this official guide.

Additional configurations
  • Create a collection and add the Authorization for this collection. All of its request will use the same auth method.
  • Create variables (on tab "Variables") to store "CLIENT ID" (client_id) and "CLIENT SECRET" (as client_secret), then use them in the form by {{client_id}} and {{client_secret}}.

Location problem

πŸ‘‰ List of endpoints (containing location inside).
πŸ‘‰ LIst of location information you can use with Dialogflow.

You have to use the same endpoint and location information in the API/SDK. If you use them differently, for example,

https://global-dialogflow.googleapis.com/v2/projects/-/locations/europe-west1/agent:search

You will meet an error like below,

"Please switch to 'europe-west1-dialogflow.googleapis.com' to access resources located in 'europe-west1'."

In the SDK documention, they don't mention about the location you need to use in the agent property. For example, they say "parent can be projects/<Project ID or '-'>", but you can add the location information inside it like that

const parent = (location) => "projects/-" + "/locations/" + location; 

πŸ’‘They are the same (for endpoints):

dialogflow.googleapis.com
us-dialogflow.googleapis.com
global-dialogflow.googleapis.com