Built-in Intents

When you publish your Actions, Google Assistant makes them discoverable by users through the Actions directory. You can also make your Action implicitly discoverable by associating it with a built-in intent.

How to use built-in intents

  • A built-in intent is a unique identifier that tells the Assistant that your Action is suitable to fulfill a specific category of user requests, such as playing games or ordering tickets.
  • Built-in intents extend the range of invocation terms or phrases that users can provide to launch your Action, without requiring you to define those terms explicitly (for example, your invocation phrases could be "Read inspirational quotes" or "Check my credit score").
  • During Action discovery, the Assistant can use information about your Action, including its attached built-in intents, to suggest it to users only if it is relevant.
  • To minimize conversational round-trips, the Assistant will attempt to extract parameters from user queries that map to built-in intents and pass them on to your Action. To learn more about these parameters and see examples of user queries, see the Built-in intents reference.

Requirements

In order to use built-in intents, the locale of your Action project must be one of the following:

  • en-US
  • de-DE (coming soon)
  • fr-FR (coming soon)
  • ja-JP (coming soon)
  • ko-KR (coming soon)

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 app, 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. Dialogflow console (Adding a Dialogflow event.)
  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. Dialogflow console (Attaching a built-in intent to your agent.)
  4. Click Save.

Actions SDK

If you are using the Actions SDK to build your app, you need to 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 Submit your app for approval.

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 all the 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.

Let’s take the actions.intent.CHECK_AIR_QUALITY built-in intent as an example. Its schema 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 are using 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

In addition to the best practices for action discovery, 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.
  • Use built-in intents for in-dialog triggering: After users trigger your Action initially via explicit invocation, you should pivot them towards invoking built-in intents during the conversation. You can do this by adding your own grammars for in-dialog triggering.

Built-in intents roadmap

We are actively working on implementing the following built-in intents, and they will be available soon.

You can send us feedback about other intents that you would like to see filling out this form.

Built-in intents coming soon
Play sounds Tell jokes Check news Play movie
Play video Call Manage messages Take photos
Edit photo Continue watching Cast Find recipe for ...
Add to story Check mentions Start exercise Start routine
Add to playlist Manage videos Manage photos Share photos