Build

When you are done setting up an Actions project and a Dialogflow agent, you can start building your agent. In Dialogflow, intents represent a mapping between what a user says and the corresponding response. You build your intents based on your conversation design, typically creating an intent for each turn (a back and forth exchange between the user and your agent) of the conversation and mapping Actions to specific Dialogflow intents.

The next sections show you how to create intents that map to specific Actions on Google concepts, such as Actions and helpers. For more information about how Dialogflow intents and Actions on Google intents map to one another, see the Actions on Google integration documentation.

Access the Actions on Google integration

To access the Actions on Google integration:

  1. Click on Integrations in the left menu. If you don't see the menu, click the menu menu button in the upper left corner.

  2. Click on the Google Assistant integration to open the settings.

From here, you can specify, test, and manage your Actions.

Specify Actions

To mark specific Dialogflow intents as Action intents, use the Actions on Google integration screen. This screen lets you specify your explicit invocation intent (the intent that is matched when users say the invocation name defined in your Actions on Google project) and any other custom Actions that your Dialogflow agent can support (implicit invocation).

  1. Set the explicit invocation intent with the drop-down menu. By default, all agents are created with one Default Welcome Intent that is automatically set as the explicit invocation intent. When users say your invocation name, this intent is matched.

  2. Add additional intents to the Implicit invocation field. This lets you specify additional Actions that you support outside of the default Action. The training phrases in these intents specify the invocation phrases for your Action. When defining these invocation phrases, follow these guidelines:

    • Don't specify "reserved" wording from name invocation or Action invocation and "trigger phrases". For example, don't use "talk to <action name>", "talk to", or "let me talk to".
    • Don't specify training phrases that contain only a @sys.any entity. You should be much more specific, such as "find recipes for @sys.any".

Handle unrecognized Actions

When users try to specify an Action that isn't supported, Dialogflow can trigger a specific fallback intent to handle these cases. To enable this behavior, create a fallback intent that sets an input context to be google_assistant_welcome and specify the appropriate responses to users:

  1. In the left navigation of Dialogflow, click Intents.
  2. Click the overflow menu icon next to the Create Intent button and select Create Fallback Intent.
  3. In the Contexts section, specify google_assistant_welcome as the input context. Make sure you hit the Enter key so the context is properly set.
  4. Specify responses that are appropriate for an unrecognized Action in the Response section.
  5. If you want to use fulfillment to handle this intent:

    1. In the Action section, specify an Action name.
    2. Click the Fulfillment section header and select Enable webhook call for this intent.
    3. When Dialogflow triggers this intent, you can call the getRawInput() method of the client library to obtain the unrecognized Action phrase. You can then return responses in your fulfillment logic based on the unrecognized Action phrase or other logic.

Build dialogs

You build dialogs by creating Dialogflow intents, specifying training phrases to define the grammar or what users need to say to trigger an intent and the corresponding response to the intent. Dialogflow also supports Assistant rich responses, like basic cards, lists, and more. You can create as many intents as you'd like to define your entire conversation's grammar.

To create an intent:

  1. Click the add sign by the Intents menu item in Dialogflow's left navigation. The Intent Editor appears where you can enter the following information:

    • Intent name is the name of the intent that's displayed in the IDE. This name is also used to register intent handlers in your fulfillment code if you're using the Actions on Google fulfillment library.
    • Contexts let you scope the triggering of the intent to specific cases. This is an advanced feature of Dialogflow, so read the Dialogflow documentation on contexts for more information.
    • User says phrases define what users need to say (the grammar) to trigger the intent. Type a few phrases here (5-10) of what users can say to trigger the intent. Dialogflow automatically handles natural variations of the example phrases you provide.
    • Events trigger intents without the need for users to say anything. One example event is the GOOGLE_ASSISTANT_WELCOME event, which allows the Google Assistant to invoke your Action. This event is used for your agent's default, explicit Action. See the Actions on Google documentation for more information on built-in intents and helper intents, which require you to assign events to the corresponding Dialogflow intents.
    • Action & parameters defines what to data to pass to fulfillment, if fulfillment is enabled for this intent. This includes data parsed from the user input and the name that you can use in your fulfillment to detect which intent was triggered. You'll use this name later when you create an Action map, which maps an intent its corresponding fulfillment logic. See the Actions and Parameters for more information about defining Actions.

    • Response - The Dialogflow Response Builder lets you define the response to this intent directly within Dialogflow, without calling fulfillment. This feature is useful for responses that are static and don't require fulfillment. You might use this for things such as simple welcome or goodbye messages. However, you will likely use fulfillment to respond to your users for most intents.

    • Fulfillment specifies whether or not you want to call your fulfillment when this intent is triggered. You most likely will enable this for most intents in your Dialogflow agent. To see this item in the intent, you must have fulfillment enabled for the agent in the Fulfillment menu.

    • Actions on Google lets you specify platform-specific settings for the intent. Currently, only End conversation is supported. This closes the mic and ends the conversation after the corresponding response is returned to the user. This setting only honored if you don't use fulfillment for the intent.

  2. In the Responses section, switch to the Google Assistant tab and click Add Responses. We'll show you how to add a basic card.

  3. From the list, choose Simple Response. Actions on Google requires a simple response (text and/or voice only) for each response.

  4. In the simple response field, enter a phrase to introduce the card.

  5. Click Add Responses again and select Basic Card.

  6. Add information to build the card. The following screenshot shows values for each field and how they are rendered:

    • Image URL - https://blog.dialogflow.com/images/logo.svg
    • Image accessibility text - Dialogflow logo
    • Title - Dialogflow
    • Subtitle - Build natural and rich conversational experiences
    • Text - This is a basic card!
    • Weblink title - Dialogflow website
    • Weblink - https://dialogflow.com
  7. Click the Save button.

Call helpers

For more information on how to use helpers, see the Actions on Google Helpers documentation.

Build Dialogflow agent fulfillment

Your agent already acts as fulfillment for your Actions, but if you need to build fulfillment for your actual Dialogflow agent (for example, to call a REST API or a backend database) you can do that as well. You can turn on fulfillment on a per-intent basis.

When an intent is triggered that uses fulfillment, you receive a request from Dialogflow that contains information about the intent. You then respond to the request by processing the intent and returning a response. The Dialogflow fulfillment protocol defines the request and response formats.

We highly recommend that you use the Node.js client library to process requests and return responses. Here's the general process for using the client library:

  1. Initialize the DialogflowApp object. This object automatically handles listening for requests and parsing them so that you can process them in your fulfillment.
  2. Create functions to handle requests. These functions process the user input and other components of the intent and build the response to return to Dialogflow.

Initialize the DialogflowApp object

The following code instantiates DialogflowApp and does some boilerplate Node.js setup for Google Cloud Functions:

'use strict';

const {dialogflow} = require('actions-on-google');
const functions = require('firebase-functions');

const app = dialogflow({debug: true});

app.intent('Default Welcome Intent', (conv) => {
  // Do things
});

exports.yourAction = functions.https.onRequest(app);

Create functions to handle requests

When users speak a phrase that triggers an intent, you receive a request from Dialogflow that you handle with a function in your fulfillment. In this function, you'll generally do following things:

  1. Carry out any logic required to process the user input.

  2. Build your responses to respond to triggered intents. Take into account the surface that your users are using to construct appropriate responses. See surface capabilities for more information on how to cater responses for different surfaces.

  3. Call the ask() function with your response.

The following code shows you how to build two TTS reponses that handles an invocation intent (input.welcome) and a dialog intent (input.number) that welcomes the user to your Action and echoes back a number that a user has spoken for a Dialogflow intent with the name:

const app = dialogflow();

app.intent('Default Welcome Intent', (conv) => {
  conv.ask('Welcome to number echo! Say a number.');
});

app.intent('Input Number', (conv, {num}) => {
  // extract the num parameter as a local string variable
  conv.close(`You said ${num}`);
});

Instead of having individual handlers for each intent, you can alternatively add a fallback function. Inside the fallback function, check which intent triggered it and do the appropriate thing accordingly.

const WELCOME_INTENT = 'Default Welcome Intent';
const NUMBER_INTENT = 'Input Number';
const NUMBER_ARGUMENT = 'num';

// you can add a fallback function instead of a function for individual intents
app.fallback((conv) => {
  // intent contains the name of the intent
  // you defined in the Intents area of Dialogflow
  const intent = conv.intent;
  switch (intent) {
    case WELCOME_INTENT:
      conv.ask('Welcome! Say a number.');
      break;

    case NUMBER_INTENT:
      const num = conv.arguments.get(NUMBER_ARGUMENT);
      conv.close(`You said ${num}`);
      break;
  }
});

No-match reprompting

When Dialogflow cannot match any of the input grammars defined in the User says portion of your intents, it triggers a fallback intent. Fallback intents typically reprompt the user to provide the necessary input for your Action. You can provide reprompt phrases by specifying them in the Response area of a fallback intent or you can use a webhook to provide responses.

To create fallback intents:

  1. Click Intents in the left navigation of Dialogflow.
  2. Click the menu icon to the right of the Create Intent button and select Create Fallback Intent. Alternatively, click the Default Fallback Intent to edit it.

  3. Specify reprompt phrases to speak back to users. These phrases should be conversational and be as useful as possible to the user's current context.

    To do this without fulfillment:

    Specify phrases in the Response area of the intent. Dialogflow randomly chooses phrases from this list to speak back to users until a more specific intent is triggered.

    To do this with fulfillment:

    1. Select the Use webhook checkbox in the Fulfillment area of the intent.
    2. In your fulfillment logic, handle the fallback intent that gets triggered like with any other intent, as described in creating functions to handle requests.

    For example, the following function uses the app.data object (an arbitrary data payload that you can use to maintain state) to store a counter that tracks how many times a fallback intent is triggered. If it's triggered more than once, the Action quits. You can then reset the counter when any other intent is triggered.

app.intent('Default Fallback Intent', (conv) => {
  conv.data.fallbackCount++;
  // Provide two prompts before ending game
  if (conv.data.fallbackCount === 1) {
    conv.contexts.set(DONE_YES_NO_CONTEXT, 5);
    conv.ask('Are you done playing Number Genie?');
  } else {
    conv.close(`Since I'm still having trouble, so I'll stop here. ` +
      `Let’s play again soon.`);
  }
});

See the Number Genie sample for details on how to implement this.

Using contexts

Use contexts if you want Dialogflow to trigger falllback intents only in certain situations. This is helpful if you want to have different fallback intents for different no-match scenarios.

  • If you don't set contexts on a fallback intent, it's considered to be a global fallback intent that Dialogflow triggers when no other intent is matched. You should only have one of these defined if you choose to use one.
  • If you set input contexts on a fallback intent, Dialogflow triggers this fallback intent when the following is true:

    • The user's current contexts are a superset of the contexts defined in the intent.
    • No other intent matches.

    This lets you use multiple fallback intents with different input contexts to customize no-match reprompting to specific scenarios.

  • If you set an output context on a fallback intent, you keep the user in the same context after the fallback intent is triggered and processed.

See Dialogflow Contexts for more information.

No-input reprompting

When you call the ask() method to return responses to users, you can specify an array of prompts that is spoken to users if the Google Assistant can't detect any input. The Google Assistant speaks these prompts in order, and you can specify up to three prompts. For example:

app.intent('actions.intent.MAIN', conv => {
  conv.noInputs = [
    'Are you still there?',
    'Hello?',
    new SimpleResponse({
      text: 'Talk to you later. Bye!',
      speech: 'Talk to you later. Bye!'
    })
  ]
  conv.ask('What's your favorite color?')
})