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)
Code language: JavaScript (javascript)

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.

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