Build Your First App with Dialogflow

Apps for the Google Assistant are conversational in nature and let you extend the Assistant's functionality with your own conversations that let users do things like schedule appointments, play a game, or get updates about the latest news.

This guide shows you how to build a simple Silly Name Maker app for the Google Assistant that returns a user's silly name by prompting the user for a favorite color and lucky number. You'll also learn the basic concepts of Actions on Google and the Google Assistant and how to build for these platforms using Dialogflow.

App architecture

Here's how a typical app for the Google Assistant works, which consists of three main parts:

Actions and Invocation

Actions on Google defines how users can invoke apps for the Assistant through action-based commands such as "book a ride" or "play a game". Every app must define a main action that lets users invoke the app by it's name. In addition, every app can define additional actions that deep-link into the app through different entry points.

In this tutorial, you'll define just one default action, which will let users invoke your app by saying something like, "Ok Google, talk to Silly Name Maker".

After defining how users invoke your apps with actions, you then publish the actions with Actions on Google. Users can then discover the actions through the Assistant directory within the Google app on Android or the Assistant App for iOS.

Conversation

This is the UI of your app and defines how users interact with your app after it's invoked by Actions on Google. You'll use Dialogflow to define your conversation's grammar (what users can say to your app).

In addition, Dialogflow gives you built-in machine learning and natural language understanding, so you don't have to define a fully exhaustive grammar. You can also define how to parse typed parameters from the user's input in Dialogflow, making it even easier to understand what the user said. Once you build your conversation's grammar in Dialogflow, you define how you respond to the user in fulfillment.

In this tutorial, you'll create a very simple grammar that defines how users can provide their favorite color and lucky number.

Fulfillment

Dialogflow handles much of the heavy lifting of understanding natural language and parsing the data you need from user input. However, during the conversation with the user, you typically need to carry out some business logic to respond to the user and to complete the requested action. You do this with a web service (called fulfillment) that implements the Dialogflow webhook, a JSON-based protocol that defines how apps should integrate into the Assistant with Dialogflow.

When users say something, you receive the raw text and a set of parsed parameters from that input. You then use this data to return a response to move the conversation forward. When you're done conversing with the user, you can fulfill the requested action.

In this tutorial, you define how Dialogflow parses the color and number from the user's input, receive this data in your fulfillment, and respond back with the user's silly name.

Design the conversation

Before you begin creating an app, you should always map out it's conversation by writing sample dialogs. These dialogs give you a good reference point when you eventually start building your app. For the Silly Name Maker app, we've provided a couple of simple dialogs, which are described below:

Happy path

App: Hi! Welcome to Silly Name Maker! Let's get started. What is your lucky number?
User: 5
App: What is your favorite color?
User: Yellow
App: Alright, your silly name is Yellow 5! I hope you like it. See you next time.

User provides bad input

App: Hi! Welcome to Silly Name Maker! Let's get started. What is your lucky number?
User: Dog
App: Hmm that doesn't sound like an number to me. What's your lucky number again?"
User: 22
App: What is your favorite color?
User: Blue
App: Alright, your silly name is Blue 22! I hope you like it. See you next time.

Create an Actions project and Dialogflow agent

To develop for Actions on Google, you need to create an Actions project and Dialogflow agent. The Actions project allows lets you register your actions, manage your app through the approval process, view analytics for your app, and more. The Dialogflow agent defines what users can say to your app and how your app processes users input.

To create a project and agent:

  1. Go to the Actions on Google Developer Console.
  2. Click on Add Project, enter SillyNameMaker for the project name, and click Create Project.
  3. In the Overview screen, click BUILD on the Dialogflow card and then CREATE ACTIONS ON Dialogflow to start building actions.
  4. The Dialogflow console appears with information automatically populated in an agent. Click Save to save the agent.
  5. Your agent calls some fulfillment logic that you'll build later to return a response with the user's silly name. Enabling fulfillment for your agent enables some UI fields that we'll need later, so let's do this now:
    1. Click the Fulfillment menu item.
    2. Move the Disabled slider to the right to Enabled.
    3. Enter a dummy URL for now, https://silly.name.maker. We'll update this URL when you build and deploy your fulfillment.

  6. Click Save.

Define actions and invocation

When you create a Dialogflow agent, a Default Welcome intent is automatically created. This intent represents the main entry point into your conversation or main action of your app. All your apps must have this main action defined, so that Actions on Google knows how to invoke your app. This intent has the following characteristics:

  • The Events section of the intent specifies a WELCOME event, which signifies that this intent is the default entry point into your app. Each agent must have one and only one intent that declares this WELCOME event. The Google Assistant uses this event to trigger your app when users invoke your app by name, such as with "Ok Google, talk to Silly Name Maker".

  • The Action field specifies an input.welcome name. When an intent is triggered, this action name is sent to your fulfillment so it can map the action's name to the task to carry out. Because this welcome intent doesn't need to use fulfillment (all it does is respond with a static response), you can leave this as-is, because it's never used.

  • In the Response section, there are default, static text responses. This lets you respond to users without a call to your fulfillment. The Default Welcome Intent contains pre-populated responses that you should remove to add your own.

Now that you know a little about the welcome intent, lets modify it to suit our needs:

  1. In the left-navigation menu, click Intents and select the Default Welcome Intent.

  2. In the Response section, delete the pre-populated responses in the Text response fields by clicking on the trash can icon in the upper-right corner.

  3. Click on ADD MESSAGE CONTENT > Text response, specify the following response instead, and click Save:

    Hi! Welcome to Silly Name Maker! Let's get started. What is your lucky
    number?
    

  4. Click Save.

Now, when users invoke your app, they know that they're entering your app's experience and what to say next. In general, your responses should guide users on what to say next and to stay within your conversations' grammar, which we'll further define in the next section.

Define your conversation's grammar

Dialogflow intents define your conversation's grammar and what tasks to carry out when users speak particular phrases of your grammar. Because Dialogflow includes a natural language understanding (NLU) engine, you don't need to be exhaustive when defining the phrases; Dialogflow automatically expands on the phrases you provide and understands many more variations of them.

Create an intent that defines how users need to provide their lucky number and favorite color to generate the silly name.

  1. In the left navigation, click the + icon by the Intents menu item.
  2. In the Intent name field, enter make_name.
  3. In the User says field, enter My lucky number is 23 and hit Enter.
  4. Click and highlight the number 23 and assign it the @sys.number entity in the drop-down menu that appears. Dialogflow might try and intellgiently assign this automatically to another entity, such as @sys.age. You can always change it's guess to another entity.

  5. Provide more variations for the User says phrases and assign any number within those phrases the @sys.number entity:

    • 23
    • The luckiest number I have is 12.

  6. In the Actions section, select the REQUIRED checkbox for the number parameter. This tells Dialogflow to not trigger the intent until the parameter is properly provided by the user.

  7. Click on Define prompts for the parameter and provide a reprompt phrase. This phrase is spoken to the user repeatedly until the Dialogflow detects a number in the user input.

  8. In the Actions section, enter a new parameter with the following information:

    • Required - Select the checkbox
    • Parameter name - color
    • Entity - @sys.color
    • Value - $color
    • Prompts - What is your favorite color?

  9. Enter make_name for it's name and click SAVE.

  10. In the Fulfillment section, select the Use webhook checkbox. This tells Dialogflow to call your fulfillment to generate a response to the user instead of using Dialogflow's response feature.

  11. In the Actions on Google section, select the End conversation checkbox. This tells Dialogflow to relinquish control back to the Google Assistant after your fulfillment returns a response to the user.

  12. Click SAVE to save the entire intent.

That's it! You've successfully declared your conversation's grammar with Dialogflow intents. You've also used Dialogflow's built-response feature to return a static response to the user when they invoke your app. You also created an intent that uses fulfillment to return a response, which you'll now need to build.

Build fulfillment

You'll now build a Cloud Function for Firebase for your fulfillment logic. Your fulfillment takes the parsed user input that Dialogflow returns and responds with the user's silly name.

  1. Download and install Node.js.
  2. Set up and initialize the Firebase CLI with the following command.

    npm install -g firebase-tools
    
  3. Authenticate the firebase tool with your Google account with the following command:

    firebase login
    
  4. Create a directory called sillynamemaker and initialize the directory with the following commands:

    mkdir sillynamemaker
    cd sillynamemaker
    firebase init
    

    You should see the following screen:

        Which Firebase CLI features do you want to setup for this folder? Press Space 
        to select features, then Enter to confirm your choices. 
         ◯ Database: Deploy Firebase Realtime Database Rules
        ❯◯ Functions: Configure and deploy Cloud Functions
         ◯ Hosting: Configure and deploy Firebase Hosting sites
    

  5. Select Functions from the interactive CLI menu and hit the Enter key.

  6. Select your Actions project ID from the screen (it should have silly-name-maker in the string). You can find the project ID in your Dialogflow agent's settings as well.
  7. The firebase init command created two files, package.json and index.js. Edit them to make them look like the following examples:

    sillynamemaker/functions/package.json

    This file declares package dependencies for your fulfillment, including the Actions on Google and Cloud Functions for Firebase Node.js client libraries.

    {
      "name": "silly-name-maker",
      "description": "Find out your silly name!",
      "version": "0.0.1",
      "author": "Google Inc.",
      "engines": {
        "node": "~4.2"
      },
      "dependencies": {
        "actions-on-google": "^1.0.0",
        "firebase-admin": "^4.2.1",
        "firebase-functions": "^0.5.7"
      }
    }
    

    sillynamemaker/functions/index.js

    This file defines your fulfillment logic. Here's some major things you need to know:

    1. When Dialogflow intents are triggered, the intent's action name (declared in the action area of the intent) is provided to you in the request to your fulfillment. You use this action name to determine what logic to carry out.
    2. Within every request to your fulfillment, if Dialogflow parsed parameters from the user input, you can access the parameter by name. Here, you declare the names of the parameters, so you can access them later.
    3. This function fulfills the action by generating a silly name. It's called whenever the make_name intent is triggered. It uses the paramerts from the user input to generate the name.
    4. Action maps in the Node.js client library let you map intent names to functions, so that when your fulfilment receives a request, a function can automatically be called based on the action name. You use the action name variable that you declared earlier and map that name to the make_name function.

      'use strict';

      process.env.DEBUG = 'actions-on-google:*'; const App = require('actions-on-google').DialogflowApp; const functions = require('firebase-functions');

      // a. the action name from the make_name Dialogflow intent const NAME_ACTION = 'make_name'; // b. the parameters that are parsed from the make_name intent const COLOR_ARGUMENT = 'color'; const NUMBER_ARGUMENT = 'number';

      exports.sillyNameMaker = functions.https.onRequest((request, response) => { const app = new App({request, response}); console.log('Request headers: ' + JSON.stringify(request.headers)); console.log('Request body: ' + JSON.stringify(request.body));

      // c. The function that generates the silly name function makeName (app) { let number = app.getArgument(NUMBER_ARGUMENT); let color = app.getArgument(COLOR_ARGUMENT); app.tell('Alright, your silly name is ' + color + ' ' + number + '! I hope you like it. See you next time.'); } // d. build an action map, which maps intent names to functions let actionMap = new Map(); actionMap.set(NAME_ACTION, makeName);

      app.handleRequest(actionMap); });

  8. From the sillynamemaker/functions directory, run the following command to get the project dependencies:

    npm install
    

Deploy the fulfillment

  1. From the sillynamemaker/functions directory, deploy the fulfillment to the cloud with the following command:

    firebase deploy --only functions

    The deployment takes a few moments. Once completed, you'll see output similar to the following. You'll need the Function URL to enter in Dialogflow.

    ✔  Deploy complete!

    Project Console: https://console.firebase.google.com/project/sillynamemaker-abb1d/overview Function URL (sillyNameMaker): https://us-central1-sillynamemaker-abb1d.cloudfunctions.net/sillyNameMaker

  2. In Dialogflow's left navigation, click on the Fulfillment menu item.

  3. Enter the function's URL in the URL field and click Save.

Preview the app

Now that you have your fulfillment deployed and properly set in Dialogflow, you can preview the app in the Actions simulator.

To preview your app:

  1. Turn on the Web & App Activity, Device Information, and Voice & Audio Activity permissions on the Activity controls page for your Google account. You need to do this to use the Actions Simulator, which lets you test your actions on the web without a hardware device.

  2. Click on Integrations in Dialogflow's left navigation, and move the slider bar for the Actions on Google card.

  3. Click on the Actions on Google card to bring up the integration screen and click TEST. Dialogflow uploads the agent to our servers so you can test it out in the Actions simulator.

  4. In the Test your Assistant app section of the integration screen, click on the Actions Simulator link to open a new browser for the Actions simulator.

  5. In the Actions Simulator, enter talk to my test app in the Input area of the simulator to test the app.

  6. Enter a number and then a color when prompted to receive your silly name.

Next steps

This app is only available for testing with the account that you use to develop with. When you start building your own apps and want to make them available to all users, you have to submit the app for approval by our review team.

See the Dialogflow developer guide for more information on how to build apps for the Assistant with Dialogflow.