Home / DialogFlow ES / How to bulk upload intents from a CSV file in Dialogflow
DialogFlow ES

How to bulk upload intents from a CSV file in Dialogflow

Check out my courses Learn Dialogflow ES and Learn Dialogflow CX if you would like to learn Dialogflow in depth. 

If you are creating a large FAQ chatbot in Dialogflow, typing out all the intents one by one can be a slooooooooow and painful process.

Thankfully, Dialogflow has an agent ZIP file import feature, and it is possible to programmatically create this ZIP file.

Note: this article talks about the use case where you have already identified the Dialogflow intents. If you haven’t yet defined the intents and the training phrases inside them, check out my tool which can help you automatically extract Dialogflow intents from your chat logs.

Alternatively, you can use the knowledge base feature. But there are some important differences.

I have created a table summarizing the differences between knowledge based FAQ bots and intent based FAQ bots.

Intent Based FAQ BotKnowledge Based FAQ Bot
How we build itUsing intents and training phrasesUsing the knowledge base feature
Support for multiple responses for the same queryNoYes
Multiple training phrases per intentYesNo
Supports entities in training phrasesYesNo
Support for contexts (and follow up)YesNo
Easy to construct rich responses (e.g. for Dialogflow Messenger)YesNo
Use term reinforcement for adding weights to specific words and phrasesYesBlackbox
Allows us to minimize intra-intent variance and maximize inter-intent variance (as recommended by Google)YesBlackbox
Read full article

As you can see, unless you are sure you need multiple responses from your chatbot, you are much better off going with the Intent Based FAQ Bot.

There are also other tools which can help speed up the process of creating large FAQ bots.

Video Table of Contents

[00:00] BotFlo App Website

[00:23] Automatically identify Dialogflow intents from chat logs

[01:18] Bulk upload Dialogflow intents from spreadsheet

[02:14] Convert Dialogflow agent ZIP file to CSV

[02:50] Quickly search across all Dialogflow ES intents

[03:38] Download Dialogflow ES conversation logs

[04:09] Convert Dialogflow conversation history to CSV

[04:30] Version Diff: Compare two Dialogflow agent ZIP files

In this article, I describe how you can type out your intent information into a spreadsheet and then use a CSV export of your spreadsheet to generate a Dialogflow agent ZIP file. I also discuss the different aspects you need to consider as you try to use this approach for more complex FAQ bots.

By following this template, you should be able to build a tool which can create a Dialogflow FAQ chatbot with the push of a button.

I also have an app which can do this for you, if you don’t want to build such a tool by yourself.

This article talks about text-only FAQ chatbots. If you would like to see how to do something similar for rich response channels such as Dialogflow Messenger, Facebook Messenger and Google Assistant check out the follow up article.

Want to build it yourself?

First, let us export a ZIP file for a very simple Dialogflow agent and take a look at the directory and file structure, as well as the contents of the JSON file.

I will use an agent which has exactly two intents (taken from the prebuilt smalltalk agent).

Prebuilt smalltalk agent

I went to the Export and Import tab, and clicked on Export the ZIP file for this simple agent. Once you uncompress the ZIP file, the following file/folder structure is revealed:

Unzipping the agent ZIP file and opening the folder shows us these files

And you can inspect the smalltalk.agent.be_clever_usersays_en.json.

You see that it is an array of JSON objects, and an individual JSON object has an id, the data, isTemplate, count and updated fields.

Structure of a single JSON file

Next, notice the response JSON object smalltalk.agent.be_clever.json

The responses field is an array and contains the messages array which has the responses

Say, you want to add your own intent.

You simply need to follow the same pattern as the other intents, and create two new JSON files, and ZIP it up and import it into Dialogflow. 

So you generate a random GUID, and get all the other stuff exactly in place. In my example, I made a copy of both the smalltalk.agent.be_clever_usersays_en.json and the smalltalk.agent.be_clever.json files and added a random GUID in the copied files, and created a ZIP file and tried to do a restore.

You can edit this JSON file and change the name field

Make sure the filenames match:

Make sure all the JSON filenames match

Here is what the end result looks like after the import:

If you ZIP the folder again and Restore it, you will see the new intent

In fact, an even easier option is to simply omit all the GUIDs in the intents as well as the userSays as you create your ZIP file. Dialogflow will simply see that the ID is missing and generate its own.

But there are a couple of important things to note:

  • Dialogflow will not permit two intents with the exact same name – be sure to change the name
  • Your files should be of the format filename.json and filename_usersays_en.json – if you don’t follow this convention, the import doesn’t work correctly

Simple question and answer FAQ chatbot

If you just want to create a simple FAQ bot with one question corresponding to one answer, it requires a simple CSV format. There is a column with a user says message (Query), and then another column with the text response (Response).

What you want to do: You upload this CSV format, and you have an agent at the end of it.

You can have a very simple format with a single question and a single answer

How to convert your CSV file into Dialogflow agent ZIP File

These are the steps to take your 2 Column CSV file specified in the format above and convert it into a Dialogflow agent ZIP file in BotFlo.

1 Download the 2 Column CSV file

2 Upload your CSV file

Now upload the CSV file you downloaded in the previous step.

Upload your CSV file (make sure it is in the correct format)

3 Download agent ZIP file

Once you click on Convert, you will be able to download the agent ZIP file to your local computer

4 Restore agent ZIP file in Dialogflow

Restore the agent ZIP file inside your Dialogflow console

5 Test your agent

And test your agent using the builtin Dialogflow Messenger integration

How to add multiple training phrases per intent

Now, the simple 2 Column CSV format is not sufficient. For example,

  • how can you handle multiple user says (training) phrases per intent?
  • what if you want to add multiple text responses?
  • what should be used as the intent’s name?

Suppose we create the following CSV column structure to accommodate the points from the previous section. You have an intent ID, followed by intent name, followed by userSays phrase, and the final column will be your text response.

For example, this is what the CSV format would look like (screenshot taken from my BotFlo app). All rows must have an intentID to identify the intent. Notice that you can have multiple queries (training phrases) and multiple responses per intent.

Four column format

While this gives you the ability to use multiple userSays phrases as well as multiple text responses, it is also more complex to process this format.

How to add input and output contexts

If you would like to add input and output contexts into the CSV format, you need to consider the following:

  • you can have multiple input and output contexts per intent
  • every output context should have an associated context lifespan

Here is the format I came up with for this purpose (again taken from my BotFlo app):

Adding more columns to accommodate contexts, actions, and webhook setting

What about entities?

Specifying entities inside this CSV format is more complex.

Why is this?

It’s because when you add a training phrase containing an entity, Dialogflow automatically parses the entity value (annotates it, that is). For example, you can see below that the word tomorrow is automatically annotated as a date entity.

Dialogflow automatically parses and annotates entities when it can

If you download and inspect the JSON of this intent, it looks like this:

JSON file output of the entity annotation

So adding entities via a CSV format will have two issues:

  • it makes the CSV format more complex (not such a big problem)
  • the annotation will not automatically work (bigger problem)

For example, you might annotate a name as @sys.given-name in your CSV file, for example. But that will not automatically be accepted by Dialogflow which might reject the entity value since its system entity cannot handle it.

(I am working on a solution to this also, and will update this post soon).

What about followup intents?

Sometime around May 2017, Dialogflow (which was then API.AI) introduced the followup intents feature. These allowed you to have a hierarchy of intents, like below.

Example follow up intent hierarchy

Since the number of hierarchical levels is (theoretically) unlimited, you can imagine that it is not possible to capture this very complex structure in the CSV format at all.

So an app which can convert a CSV file into a Dialogflow agent ZIP file will NOT be able to capture followup intents.

If you want to use followup intents in your Dialogflow agent (make sure you read this article to learn about some situations where you should not use follow up intents), you cannot use this approach.


Here is a summary of how the BotFlo app works.

Feature2 Column CSV (Simple FAQ Bot)4 Column CSV (Basic FAQ Bot)10 Column CSV (Advanced FAQ Bot)
Multiple training phrases per intentNoYesYes
Multiple responses per intent (from which one will be randomly selected by Dialogflow)NoYesYes
Input and output contextsNoNoYes
Support for ActionNoNoYes
Support for entitiesNoNoNo
Support for follow up intentsNoNoNo

The BotFlo app gives you many tools which can speed up your Dialogflow bot development

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
Check out my YouTube courses

Dialogflow CX Beginner Tutorial

Dialogflow ES vs CX using a Decision Tree Bot

Intro to NLU for technical non-programmers

Better Dialogflow ES Bots Using the CTFS Framework

Search the autogenerated transcripts of all my YouTube videos
In this free course, I provide some tips for managing large Dialogflow ES bots without compromising on accuracy.

Similar Posts


    1. This article is about using a spreadsheet software like a CMS for creating your Dialogflow FAQ chatbot. That is, you will be manually assigning the Intent ID which groups all information for a single intent. Its goal is to speed up input for large-ish Dialogflow FAQ bots.

      I don’t think that is what you are talking about. If you tell me your end goal, maybe I can give some suggestions.

  1. Great tutorials!

    Do the intent IDs need to be in sequential order, or can they be any random number?

    Can I use your tool to upload new intents? Where I select the “Import from zip” option?

    I am looking to train the agent, by uploading new intents, or even new training phrases.

    In order to train the agents, I would need to reupload a new zipfile and restore agent?

    Or would I need to:

    1- export the agent,

    2-convert the Json file back to csv (in order to get the list of intents)

    3. then add in my new intents,

    4. then convert back to the zip file using your tool?

    1. >> Do the intent IDs need to be in sequential order, or can they be any random number?

      They can be any random number, but you do need to use a unique number per intent obviously.

      I think it is fair to say the rest of your questions boil down to whether or not my app can help with two way updates. Before I answer that question, can you tell me a little bit more about your use case
      a) what kind of bot are you creating?
      b) what kind of training will you be doing? (i.e. using system entities, or developer entities)?

      1. Cool thanks for your reply!!

        a) I will be creating an FAQ bot in a sense. That explains which products are needed based on the user input.

        So I would need to update the bot with new intents (new products).

        b) for the training, I will be using Developer entities. Each new product is an entity.

        I would need to train the bot in various ways, the user will ask for this product.

        1. I wrote a reply to your question.

          Also, is there any reason you cannot use a single entity to represent all your products, and use a webhook to fetch the answer? That might make your life much simpler.

  2. Hello Aravind,
    I have a question about your application. I would like to be able to update the intents that I have on a regular basis. Is it possible to update the intents and integrate new intents into existing hierarchies and contexts with your app?


    1. 1 If you mean update the intents from the CSV file, then yes.

      2 You cannot, however, update the intents in Dialogflow and convert the ZIP file in Dialogflow into a CSV format, because of the inherently flat structure of the CSV file.

      3 As for hierarchies, the CSV format cannot naturally support hierarchical intents (i.e. followup intents) again because of its flat structure.

      4 While in theory it is possible to modify the app to support followup intents, it will also make the UX a lot more confusing.

      5 My app does support contexts though, and you can update the contexts (and their lifespans) in the CSV and recreate the ZIP file.

    1. In theory, this could happen if the language of your agent isn’t actually English, and you use the _en suffix for the user says JSON files. If you use a non-English language you should look up the corresponding language code and use it in the usersays file names.

  3. Excellent tool! I had to wait 2 days before the app was unlocked on your free course, but was worth the wait. You should note: DialogFlow will not accept ZIPs with any intent names greater than 100 characters.

    1. A note for those reading this comment: the app is now a paid app (with a very tiny, token payment). This stops the spammers who are using disposable email addresses to sign up.

      1. Another update. I don’t offer the limited app anymore as it confused people a lot. If you want to see a demo of the app, you can check out the link mentioned in this post.

  4. Hi Aravind.
    Your tool is awesome, but it doesn’t work with more than one response. I think that it should be possible if you find a way to make a comma in between responses (this should still just be in one column). For example:
    IntentID=1; IntentName=Hello; Query=Hello; Response=Hi, Hello;

    1. Hi Ame,
      I have tested that it works with multiple responses, but only if you split the multiple responses into multiple lines in the original CSV file. Also the purpose of putting it into two different lines is that otherwise you will need to deal with the exact same issue you are talking about here – you need a separator to indicate the multiple lines (for example a comma like you have used here), and a) it is hard for people to write such text compared to simply putting it into multiple lines and b) you can run into parsing issues.

  5. Thanks for a great documentation Aravind!
    I have a question though. Do you know if it’s possible to return with a custom payload instead of the text?

    1. Hi Filip,
      This means you need to specify the custom payload JSON inside the CSV file, which I think is very hard to do. Do you mind posting your sample CSV file online where I could take a look at the custom payload’s format?