Every app is different, and not all app functionality matches an available App Actions built-in intent. For cases where there isn't a built-in intent (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 each model common ways that users express that intent.
Limitations
Custom intents have the following limitations:
- The name of a custom intent must not begin with
actions.intent
. - The name of a custom intent must be unique among custom intent names for your app.
- Only certain data types are available for parameter extraction by Google Assistant. See Supported types for the list of supported types.
- A maximum of two text parameters are supported per query. This limit does not apply to other data types.
- Only the en-US locale is supported for custom intents (device and Assistant language settings must both 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
Defining App Actions with custom intents
As with other App Actions that use built-in intents, 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, you must include the namespaces of
the attributes you want to access.
<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" />
</intent>
</capability>
...
</shortcuts>
When naming your custom intents, we recommend using the prefix
custom.actions.intent
to distinguish your custom intents from both
built-in intents and Android intents (which
function differently). Custom intent names must not begin with
actions.intent
, because that namespace is reserved for built-in intents.
For each parameter, provide the supported schema.org type
that best describes the meaning of the parameter. For example, you can use
https://schema.org/Date
to describe a date you expect to receive:
...
<intent>
<url-template android:value="https://example.com/appt{?apptType,date,time}" />
<parameter
android:name="date"
android:key="date"
android:mimeType="https://schema.org/Date" />
...
</intent>
...
Shortcut definition in shortcuts.xml
uses the same format with custom intents
as it does with built-in intents. The following code describes an App Action
that uses the referenced query patterns to trigger the SCHEDULE_APPOINTMENT
custom intent and a defined set of values, DRIVERS_LICENSE
and
VEHICLE_REGISTRATION
, for the apptType
parameter.
<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.SCHEDULE_APPOINTMENT"
app:queryPatterns="@array/scheduleApptQueries">
<intent ...>
<url-template android:value="https://example.com/appt{?apptType,date,time}" />
<parameter
android:name="date"
android:key="date"
android:mimeType="https://schema.org/Date" />
<parameter
android:name="time"
android:key="time"
android:mimeType="https://schema.org/Time" />
<!-- The following parameter has no type because the shortcuts are bound to it -->
<parameter android:name="apptType" android:key="apptType" />
</intent>
</capability>
<shortcut
android:shortcutShortLabel="Driver's License"
android:shortcutId="DRIVERS_LICENSE">
<capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
<parameter-binding
android:key="apptType"
android:value="@string/driversLicense" />
</capability-binding>
</shortcut>
<shortcut
android:shortcutsShortLabel="Vehicle Registration"
android:shortcutId="VEHICLE_REGISTRATION">
<capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
<parameter-binding
android:key="apptType"
android:value="@string/vehicleRegistration" />
</capability-binding>
</shortcut>
</shortcuts>
You can configure custom intent parameters with inline inventory,
which you can use to guide entity extraction to a set of supported entities
specified in shortcuts.xml
.
Query patterns
Each custom intent you use requires a set of queries expected from the user for that intent. This approach is unlike built-in intents, where queries are already modeled for common ways that users express tasks they're trying to do or information they seek.
In an Android resource file (usually /res/values/strings.xml
), specify query
patterns as items in a string array. When your
App Action is invoked, Google Assistant checks the user query against your
query patterns as part of matching the user's intent for fulfillment. Each query
pattern you provide represents a phrase that you consider valid for the
corresponding custom intent.
When providing query patterns for custom intents, expect each pattern to follow an explicit invocation like "open ExampleApp and" or "start ExampleApp and". For example, consider the following user queries:
- "Hey Google, open ExampleGameApp and start making a cake."
- "Hey Google, open ExampleGameApp and start making an apple pie."
- "Hey Google, start ExampleGameApp and craft 5 cake items."
- "Hey Google, use ExampleGameApp to produce cake 5 times."
To match user queries, provide query patterns that contain the portion of the query after the invocation phrase. For information you want to extract from the query (like text or a number provided by the user), you assign values to the corresponding intent parameter with placeholders in the query pattern.
To reference a parameter in a query pattern, add $
to the name of the parameter
in your pattern. For example, to create a placeholder value for a parameter such
as
<parameter name="date1" ...
(actions.xml
) or
<parameter android:name="date1" ...
(shortcuts.xml
), you would use $date1
.
The following code describes query patterns that match the above user queries and extract values for item names and the number of items to be made:
<resources>
<string-array name="ExampleQueries">
<item>start making a $text1</item>
<item>start making an $text1</item>
<item>craft $number1 $text1 items</item>
<item>produce $text1 $number1 times</item>
</string-array>
</resources>
Query patterns support Conditionals. For example, "set (an)? appointment $date $time". In this case both "set appointment today at noon" and "set an appointment today at noon" are valid queries.