Article

Adding User Interactivity with Siri Shortcuts and the Shortcuts App

Add custom intents and parameters to help users interact more quickly and effectively with Siri and the Shortcuts app.

Overview

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.

  1. Select the created Intents.intentdefiniton file.

  2. In the Xcode Menu Bar, choose Editor > New Intent.

  3. Name your intent using a VerbNoun convention, like SetAlarm, CheckOrderStatus, and so on.

  4. 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.

  5. In the title field, add a human-readable title for the Intent.

  6. 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:

  1. Expand the Relationship section.

  2. Select the desired parameter from the Parent Parameter drop-down.

  3. Select when to show the parameter from the Show If Parent drop-down.

  4. If the parent has to have an exact value, select the value from the Value drop-down.

The following example shows the storeLocation parameter has a child relationship to the orderType parent parameter. The orderType parameter is an enum with two values, pickup and delivery. When the user tells Siri they will pick up their order, the storeLocation 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:

  1. Select the Intent is user-configurable checkbox.

  2. Fill in the Summary field.

The following example shows a Shortcut that supports the soup, orderType, and deliveryLocation parameters. The summary contains the soup and orderType parameters with the deliveryLocation 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.

See Also

Shortcuts

Donating Shortcuts

Tell Siri about shortcuts to actions that the user performed in your app.

Deleting Donated Shortcuts

Remove your donations from Siri.

Soup Chef: Accelerating App Interactions with Shortcuts

Make it easy for people to use Siri with your app by providing shortcuts to your app’s actions.

Shortcut Management

Enable users to add shortcuts to Siri, and have your app suggest shortcuts to users.

Relevant Shortcuts

Display shortcuts on the Siri watch face.

enum INShortcut

An action available in your app that the system may suggest to a user or a user may add to Siri.

class INObject

An object that represents a custom intent parameter.