Built-in intents (Dialogflow)

A built-in intent is a unique identifier that you can specify to tell the Google Assistant that your Action can fulfill a specific category of user requests. For example, here are some examples of user queries that the Assistant matches to built-in intents:

  • "Play game" built-in intent: "Ok Google. Play a memory game"
  • "Get horoscope" built-in intent: "Ok Google. Get my horoscope"

During Action discovery, the Assistant can use metadata about your Action, including the built-in intents you've specified, to recommend your Action to users. To minimize conversational round-trips, the Assistant also attempts to scan parameters from the user queries and pass them on to your Action.

To see the full list of built-in intents that the Assistant supports, including their parameters and example user queries, see the Built-in intents reference.

Integrate built-in intents

Depending on how you are building your Action, there are different ways to integrate built-in intents.

Dialogflow

If you are using Dialogflow to create your Action, you can attach a built-in intent graphically from the Dialogflow console.

To attach a built-in intent with Dialogflow, follow these steps:

  1. Open the Dialogflow console, select your agent, then navigate to the Intents screen.

  2. Create or select the intent that your agent triggers when it receives a specific built-in intent. Open the Events section, and click Add Event.

    Figure 1. Adding a Dialogflow event in the Dialogflow console.

  3. In the Events field, type in the name of a built-in intent event for your agent (for example, actions_intent_PLAY_GAME).

    Figure 2. Attaching a built-in intent to your agent in the Dialogflow console.

  4. Click Save.

Actions SDK

If you are using the Actions SDK to build your Action, you must specify the mapping between built-in intents and the Actions in your Action package.

To attach a built-in intent with Actions SDK, follow these steps:

  1. Specify the built-in intent in the name field in your Action definition.
  2. Upload your action package to your Actions project using the gactions tool, as described in Actions SDK overview.

For example, the following snippet shows how you can add the CHECK_AIR_QUALITY built-in intent:

{
   "actions":[
      {
         "description":"Default Welcome Intent",
         "name":"MAIN",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.MAIN"
         }
      },
      {
         "description":"Check Air Quality",
         "name":"CHECK_AIR_QUALITY",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.CHECK_AIR_QUALITY"
         }
      }
   ],
   "conversations":{
      "conversation_1":{
         "name":"conversation_1",
         "url":"https://example.com/fulfillment",
         "fulfillmentApiVersion":2
      }
   }
}

Handle built-in intent parameters

When your Action is invoked through a built-in intent, your fulfillment might receive additional parameters. The intent schema defines the names of the parameters and their types as primitive types or schema.org entities. To view the schema for Conversational Action built-in intents, see the Built-in intents reference.

Parameters for built-in intents are optional. The Assistant handles filling the parameters with values if they can be extracted from the user's invocation of the built-in intent.

For example, the schema of the actions.intent.CHECK_AIR_QUALITY built-in intent defines four optional parameters:

Parameter Name Type
attributes A string value.
location A schema.org/Place object.
temporalCoverage A schema.org/Duration object.
timeIndicator An EnumeratedDuration (Google-specific extension).

The following code snippet shows an example of the conversation webhook (JSON) request when a user invokes your Action by saying "What's the air quality in San Francisco tomorrow?":

"inputs":[
      {
         "intent":"actions.intent.CHECK_AIR_QUALITY",
         "rawInputs":[
            {
               "inputType":"VOICE",
               "query":"what is the air quality in san francisco tomorrow"
            }
         ],
         "arguments":[
            {
               "name":"location",
               "structuredValue":{
                  "geo":{
                     "longitude":-122.41941550000001,
                     "latitude":37.7749295
                  },
                  "@context":"https://schema.org",
                  "@type":"Place",
                  "name":"san francisco"
               }
            },
            {
               "name":"temporalCoverage",
               "rawText":"2018-04-25",
               "textValue":"2018-04-25"
            }
         ]
      }
   ]

In this example, the parameters take the following values:

  • The location parameter contains the schema.org/Place value for "San Francisco".
  • The temporalCoverage parameter contains the schema.org/Duration value for tomorrow's date relative to the time of the invocation.
  • There are no values for the attributes and timeIndicator parameters because the user's invocation phrase did not include such information.

If you use the Actions on Google Client Library for Node.js, you can retrieve the value of the parameters as shown in the following snippet:

app.intent('actions.intent.CHECK_AIR_QUALITY', (conv) => {
  const attributes = conv.arguments.get('attributes');
  const location = conv.arguments.get('location');
  const temporal_coverage = conv.arguments.get('temporalCoverage');
  Const time_indicator = conv.arguments.get('timeIndicator')

  // Your Action logic. If you need to use any of the parameter values,
  // you should check first that it is defined. Arguments.get returns
  // undefined if it can't find a value for a parameter.

});

Test integrations with built-in intents

Follow these steps to test your integration:

  1. Open the Actions simulator with your test Action enabled, or open the Assistant on your device.
  2. Speak or type a query associated with that built-in intent. For example, “I want to play a game.”
  3. From the displayed app selection dialog, find your Action.
  4. Select your app to send an intent to your app.
Figure 3. The Action selection dialog resulting
from a built-in intent phrase.
Figure 4. Invoking an Action attached to a built-in intent.

Best practices for using built-in intents

You should follow these best practices when using built-in intents:

  • Map built-in intents to specific actions: When a specific built-in intent triggers your Action, send the user to the specific intent and functionality in your Action with as little friction as possible. For example, if your Action supports the PLAY_GAME built-in intent and receives that intent, you should immediately send the user to the game feature of your Action. Avoid asking the user again if they want to play a game.
  • Handle built-in intent parameters: Make sure to use the built-in intent parameter values that the Assistant sends to your fulfillment. Avoid re-prompting the user for those values.