Understanding Dialogflow service account roles and their use cases

As you try and use Dialogflow’s REST API, one of the things you will notice is that the documentation talks about “service accounts”.

In this article, we will see what these service accounts are and how they are typically used. Instead of going over any big theory (which is also important to fully master the REST API), I will just explain the basic use cases so you have a simpler starting point to understand how they work.

What are Dialogflow service accounts?

Simply put, a service account provides a way to call Google APIs from your code. Here is the official definition.

So we can use these service accounts to access your Dialogflow agent from your code.

How to create a service account for my Dialogflow agent?

Follow these steps

1 Go to your Dialogflow agent’s settings page. In the case of Dialogflow ES, you can just click on the name of the service account from the Settings page.

2 Once you are sure the correct Google cloud project has been selected, on the left hand side menu, go to APIs and Services > Credentials

3 Create a suitable service account name and click the Create button

4 Click into the Select a Role dropdown and type Dialogflow (to filter down the list)

5 Select the Dialogflow Service Agent role

6 Click Done to create the Service account

7 You will be taken to the Credentials page. Now click on the Edit icon for the service account you just created.

8 Click on the Add Key button at the bottom of the page

9 Select “Create new key” option

10 In the popup, choose JSON (which is usually already selected) and click on the Create link.

This will create a JSON key and more importantly, you will now see that a file is being downloaded to your local computer. This is the client secret key JSON file that people refer to in most of the online documentation.

Rename the client secret file to something more human readable, and save it to your local computer to a directory you will remember.

How to use the client secret file for authentication inside your code

So the basic idea goes like this:

When you use a client library for Dialogflow, you will provide the name of the client secrets JSON file you saved to your local computer. The client library code will be able to read the information inside the client secrets JSON, and do some authentication magic behind the scene, and you will now be able to call your Dialogflow agent from your code.

Here is a very simple example:

from google.oauth2 import service_account
dialogflow_key = json.load(open('<service_account_path.json>'))
credentials = (service_account.Credentials.from_service_account_info(dialogflow_key))
session_client = dialogflow_v2.SessionsClient(credentials=credentials)

Notice that the second line uses a JSON file – that is basically the client secret JSON file that you just downloaded.

Use cases

So what are all those Dialogflow roles that you saw in the dropdown box? Let us go over them one by one with their associated use cases.

Dialogflow Service Agent

The Dialogflow Service agent role is the most common role you will be using, and it can be used for your typical integration scenario. You will add this to your custom integration code, and it will allow you to detect the intent for whatever your user types. This role has the least privilege amongst the Dialogflow service account roles.

Dialogflow API Client

This role has a few more permissions than the Service agent role. In addition to being able to detect the intent, you can also update the conversation context using this role.

Dialogflow API Reader

This roles allows you to read all the intents in a single Dialogflow agent.

Dialogflow Console Agent Editor

I haven’t had a chance to use this role. I believe it is used to provide a Google account (of say a team member) access to the agent inside the Dialogflow console.

Dialogflow API Admin

This is the role with maximum privilege, and allows you to get information about as well as update/modify/delete a single Dialogflow agent.

A service account can only be used with a single Dialogflow project

One of the important things to understand is that there is a one-to-one mapping between a service account and its corresponding project. So if you have built multiple Dialogflow agents, you need to create multiple service accounts for these agents. The exception is where you explicitly provide an already defined service account (from a different project) specific privileges to the current project, but that is a more complex scenario and beyond the scope of this article.