# 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"*

> [!NOTE]
> **Note:** The 'Play Game' intent is the only built-in intent that is generally available at this time. Other built-in intents mentioned in this documentation are currently in developer preview. You can build and publish Actions that use this feature, but we are still working on fine tuning discovery and ranking.
>
> For built-in intents in developer preview, there is no user triggering initially and some
> intents will not trigger at all. For the time being, you should continue creating
> [implicit invocations](https://developers.google.com/assistant/conversational/df-asdk/discovery/implicit) and testing them in addition to
> registering for built-in intents.

During [Action discovery](https://developers.google.com/assistant/df-asdk/discovery/implicit#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](https://developers.google.com/assistant/df-asdk/reference/built-in-intents).

## 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](https://console.dialogflow.com).

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

1. Open the [Dialogflow console](https://console.dialogflow.com), 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**.

   ![](https://developers.google.com/static/assistant/df-asdk/discovery/images/dialogflow-add-event.png) **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`).

   ![](https://developers.google.com/static/assistant/df-asdk/discovery/images/bii-dialogflow.png) **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](https://developers.google.com/assistant/conversational/reference/rest/Shared.Types/Action) definition.
2. Upload your action package to your Actions project using the `gactions` tool, as described in [Actions SDK overview](https://developers.google.com/assistant/df-asdk/actions-sdk).

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](https://schema.org/)
entities. To view the schema for Conversational Action built-in intents, see the
[Built-in intents reference](https://developers.google.com/assistant/df-asdk/reference/built-in-intents).

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 `https://schema.org/Place` object. |
| `temporalCoverage` | A `https://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`](https://schema.org/Place) value for "San Francisco".
- The `temporalCoverage` parameter contains the [`schema.org/Duration`](https://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](https://developers.google.com/assistant/df-asdk/reference/nodejsv2/overview),
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.

|---|---|
| ![](https://developers.google.com/static/assistant/df-asdk/discovery/images/bii-selection.png) **Figure 3.** The Action selection dialog resulting from a built-in intent phrase. | ![](https://developers.google.com/static/assistant/df-asdk/discovery/images/bii-conversation.png) **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.