Custom intents

Every app is different, and not all app functionality matches an available App Actions built-in intent (BII). For cases where there isn't a BII for your app functionality, you can instead use a custom intent to extend your app with App Actions.

Like BIIs, custom intents follow the shortcuts.xml schema and act as connection points between Assistant and your defined fulfillments. Custom intents also have intent parameters, which you can map to parameters in your corresponding fulfillment.

Unlike BIIs, custom intents require query patterns to describe example queries that a user might say. This approach differs from built-in intents, which model common ways that users express that intent.

Limitations

Custom intents have the following limitations:

  • The name of a custom intent can't begin with actions.intent.
  • The name of a custom intent must be unique among the custom intent names for your app.
  • Only certain data types are available for parameter extraction by Google Assistant (see Supported types).
  • Custom intents must contain examples of usable query patterns (see Query patterns).
  • Each query supports a maximum of two text parameters. This limit does not apply to other data types.
  • Custom intents support only the en-US locale. Also, the device and Assistant language settings must match.

Supported types

Custom intents support the following schema.org types for parameter extraction:

  • https://schema.org/Text
  • https://schema.org/Date
  • https://schema.org/Time
  • https://schema.org/Number

Define App Actions with custom intents

As with other App Actions that use BIIs, you define a custom intent in the <capability> element in shortcuts.xml.

Capabilities are defined in the <shortcuts> root element. When you define your <shortcuts> element, include the namespaces of the attributes you want to access, as shown in the following example:

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  ...
</shortcuts>

Provide the name of the custom intent in the android:name attribute, and reference a query patterns resource file in the queryPatterns attribute.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.EXAMPLE_INTENT"
      app:queryPatterns="@array/ExampleQueries">
    <intent ...>
      <url-template
          android:value="http://custom.com{?number_of_items,item_name}" />
      <parameter
          android:name="number_of_items"
          android:key="number_of_items"
          android:mimeType="https://schema.org/Number" />
      <parameter
          android:name="item_name"
          android:key="item_name"
          android:mimeType="https://schema.org/Text"