Add custom intents and parameters to help users interact more quickly and effectively with Siri and the Shortcuts app.
By adding custom intents with parameters to your app, you can offer shortcuts that support conversational interaction in Siri and user customization in the Shortcuts app. When the user invokes your shortcut with their voice, Siri starts a dialog to collect the additional information needed to complete the shortcut. In the Shortcuts app, the user can make changes to what the shortcut will do when it’s invoked. To get an app that integrates custom intents and parameters, see Soup Chef: Accelerating App Interactions with Shortcuts and download the Soup Chef sample app.
Add an Intent Definition File to Your App Target
Choose File > New > File to add a new SiriKit Intent Definition File to your Xcode project. Make sure that you select your app target.
Define Your Intents
Create the new intent and define what the intent does.
Select the created
In the Xcode Menu Bar, choose Editor > New Intent.
Name your intent using a VerbNoun convention, like SetAlarm, CheckOrderStatus, and so on.
Make sure the category you select matches your intent’s purpose because the chosen category defines the default Siri dialog, as you will see in a later section.
In the title field, add a human-readable title for the Intent.
In the Description field, add a short sentence that describes what the intent does.
Figure 2 shows a custom intent named OrderSoup with the category, title, and description set.
Define the Intent Parameters
Before you can use the intent, you need to define the intent’s parameters such as soup, quantity, and so on. Create a new parameter by clicking the plus button in the Parameters field and selecting either a system parameter type or a custom type in the Type field. System types are predefined by the system, and custom types allow you to create your own types. Parameter names must start with a lowercase character while custom type names must start with an uppercase character.
By default, Xcode selects the User-facing checkbox. This controls whether the parameter is configurable in the Shortcuts app and resolvable at runtime in both Siri and the Shortcuts app.
Add Parameter Metadata and Siri Dialog Data
Siri can prompt users to complete shortcuts that require additional input based on the parameter metadata you provide. Set the Input fields for each parameter that you want the user to have control over, such as allowing them to order different quantities of soup through a shortcut.
You can also customize the Siri dialog for each parameter resolution result. Enter the phrase you want Siri to say to the app user in the Prompt field.
Establish Relationships Between Parameters
Use relationships between parameters to determine whether certain parameters should be prompted by voice in Siri based on their association with their parent parameter. To set the parent parameter:
Expand the Relationship section.
Select the desired parameter from the Parent Parameter drop-down.
Select when to show the parameter from the Show If Parent drop-down.
If the parent has to have an exact value, select the value from the Value drop-down.
The following example shows the
store parameter has a child relationship to the
order parent parameter. The
order parameter is an enum with two values,
delivery. When the user tells Siri they will pick up their order, the
store value is automatically used.
Define User-Configurable Shortcuts
User-configurable shortcuts are shortcuts that the user can configure in the Shortcuts app, and use interactively in Siri. To enable a shortcut for user configuration:
Select the Intent is user-configurable checkbox.
Fill in the Summary field.
The following example shows a Shortcut that supports the
delivery parameters. The summary contains the
order parameters with the
delivery in the More Options section.
Setting Intent Responses and Outputs
An intent response represents the result of the intent’s action, such as ordering soup. Response templates allow Siri to respond with an appropriate dialog when a success or failure occurs. Add properties to allow passing of data into Siri dialogs or into the shortcut output. The output allows the user to use the result of your shortcut with other actions in the Shortcuts editor.
The voice-only dialog is spoken instead of the printed dialog in circumstances where the user is not looking at a screen, such as on HomePod, CarPlay, and AirPods.
The following example shows the response for a successful order. It provides the total amount, the user’s order, and the estimated wait time.